Einen Pitch automatisieren

Agenturen durchlaufen für jeden Interessenten dieselbe Sequenz: Pitch-Projekt erstellen, KI-Modelle auswählen, Prompts hinzufügen, ein paar Tage später die Ergebnisse auslesen und — wenn der Interessent unterschreibt — den Pitch in ein Kundenprojekt umwandeln. Jeder Schritt ist über die REST-API verfügbar, mit genau denselben Limits und Fehlercodes wie im Dashboard. Ein Pitch lässt sich also aus einem CRM, einem Formular oder einem Skript starten, ohne dass jemand die UI öffnet.

Pitch-Projekte brauchen einen Agentur-Account. Sie haben keine Projektgebühr, sind auf 50 Prompts begrenzt und pausieren automatisch, wenn das Pitch-Fenster (1, 7 oder 14 Tage) schließt. Die Anzahl gleichzeitiger Pitch-Projekte ist je Paket begrenzt.

1. Pitch-Projekt erstellen

language ist Pflicht und bestimmt die Prompt-Sprache und den Länderfilter. Ein neues Projekt startet mit den Standard-Modellen deines Accounts.

curl --request POST \
  --url https://api.finseo.ai/v1/projects \
  --header 'Authorization: Bearer sk_live_xxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Prospect GmbH",
    "websiteUrl": "https://www.prospect.example",
    "language": "de",
    "isPitch": true,
    "pitchDurationDays": 7
  }'

Die Antwort enthält die id, die du für alle folgenden Aufrufe brauchst, und die aktuellen models. Eine 403 mit details.reason = "pitch_project_limit" bedeutet, dass alle Pitch-Slots deines Pakets belegt sind — wandle zuerst einen Pitch um oder lösche ihn.

2. Modelle setzen

Prompts laufen immer auf den Modellen des Projekts, setze sie also bevor du Prompts hinzufügst. Das ersetzt das komplette Set, genau wie die Seite Modell-Einstellungen.

curl --request PUT \
  --url https://api.finseo.ai/v1/projects/{projectId} \
  --header 'Authorization: Bearer sk_live_xxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{"models": ["chatgpt", "perplexity", "ai_overview", "claude"]}'

Eine 403 mit details.reason = "agency_limit" bedeutet, dass die prognostizierten monatlichen KI-Antworten das in deinem Paket inkludierte Kontingent übersteigen (details.nextPackage nennt das Upgrade). Im höchsten Paket ist der Aufruf erfolgreich und liefert stattdessen eine meteredNotice; der Überschuss wird als Overage abgerechnet.

3. Prompts hinzufügen

Lass models weg, um die Modelle des Projekts zu nutzen. language ist standardmäßig die Projektsprache. Jeder Prompt wird sofort eingereiht (enqueued: true).

import requests

API = "https://api.finseo.ai/v1"
H = {"Authorization": "Bearer sk_live_xxxxxxxx"}
project_id = "67f8a1b2c3d4e5f60718293a4"

prompts = [
    "Welche Agentur für AI-Sichtbarkeit ist in Deutschland empfehlenswert?",
    "Beste Tools um die Sichtbarkeit einer Marke in ChatGPT zu messen",
    "Prospect GmbH vs. Wettbewerber – wer ist besser?",
]
for text in prompts:
    r = requests.post(f"{API}/projects/{project_id}/prompts", headers=H,
                      json={"prompt": text, "tags": ["pitch"]})
    if r.status_code == 403:
        print("stopped:", r.json()["error"]["details"]["reason"])
        break
    r.raise_for_status()

Mögliche 403-Gründe: pitch_prompt_limit (50 Prompts erreicht), pitch_expired, agency_limit. Ein Modell, das im Projekt nicht aktiviert ist, liefert 400 model_not_enabled — zurück zu Schritt 2.

4. Ergebnisse auslesen

Gib den Workern ein paar Minuten für die ersten Antworten; ein vollständiger Pitch hat in der Regel einen Lauf pro Tag. Lies dann die KPIs, das Wettbewerber-Ranking und die Aufschlüsselung pro Prompt für das Pitch-Fenster aus:

curl --url 'https://api.finseo.ai/v1/projects/{projectId}/metrics?timeframe=7d' \
  --header 'Authorization: Bearer sk_live_xxxxxxxx'

curl --url 'https://api.finseo.ai/v1/projects/{projectId}/competitors?timeframe=7d' \
  --header 'Authorization: Bearer sk_live_xxxxxxxx'

curl --url 'https://api.finseo.ai/v1/projects/{projectId}/prompts?timeframe=7d' \
  --header 'Authorization: Bearer sk_live_xxxxxxxx'

visibilityRate, mentionRate und citationRate sind unter KPIs erklärt beschrieben. Filtere auf eine einzelne Engine mit model=<id>, wobei <id> eines der models des Projekts ist.

5. Gewonnenen Pitch umwandeln

Macht aus dem Pitch ein abrechenbares Kundenprojekt: hebt das Prompt-Limit auf, stoppt die automatische Pausierung und aktiviert alles wieder, was der Ablauf pausiert hat.

curl --request PUT \
  --url https://api.finseo.ai/v1/projects/{projectId} \
  --header 'Authorization: Bearer sk_live_xxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{"convertFromPitch": true}'

Eine 403 mit details.reason = "agency_limit" und details.limit = "projects" bedeutet, dass kein Kunden-Slot frei ist; mit details.limit = "answers" würden die Prompts des Projekts das inkludierte Antwort-Kontingent zum Vollmonatspreis übersteigen.

Verwendete Endpoints

Schritt	Endpoint
Pitch erstellen	POST /v1/projects
Modelle setzen	PUT /v1/projects/{projectId}
Prompts hinzufügen	POST /v1/projects/{projectId}/prompts
Ergebnisse auslesen	GET /metrics, GET /competitors, GET /prompts
Umwandeln	PUT /v1/projects/{projectId} mit `convertFromPitch`

Guides

Projekte

Prompts

Metriken

Wettbewerber

Quellen

Tags

Fan-outs

Tasks

Export

Attribution

Einen Pitch automatisieren

Einen Pitch automatisieren

1. Pitch-Projekt erstellen

2. Modelle setzen

3. Prompts hinzufügen

4. Ergebnisse auslesen

5. Gewonnenen Pitch umwandeln

Verwendete Endpoints

​Einen Pitch automatisieren

​1. Pitch-Projekt erstellen

​2. Modelle setzen

​3. Prompts hinzufügen

​4. Ergebnisse auslesen

​5. Gewonnenen Pitch umwandeln

​Verwendete Endpoints

Einen Pitch automatisieren

1. Pitch-Projekt erstellen

2. Modelle setzen

3. Prompts hinzufügen

4. Ergebnisse auslesen

5. Gewonnenen Pitch umwandeln

Verwendete Endpoints