> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finseo.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Einen Pitch automatisieren
> Pitch-Projekt erstellen, Modelle setzen, Prompts hinzufügen, Ergebnisse auslesen und einen gewonnenen Pitch umwandeln — der komplette Agentur-Ablauf in fünf API-Aufrufen.
# 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.
```bash theme={"system"}
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.
```bash theme={"system"}
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`).
```python theme={"system"}
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:
```bash theme={"system"}
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](/de/getting-started/kpis) beschrieben. Filtere auf eine einzelne
Engine mit `model=`, wobei `` 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.
```bash theme={"system"}
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](/de/api-reference/projects/create) |
| Modelle setzen | [PUT /v1/projects/\{projectId}](/de/api-reference/projects/update) |
| Prompts hinzufügen | [POST /v1/projects/\{projectId}/prompts](/de/api-reference/prompts/add) |
| Ergebnisse auslesen | [GET /metrics](/de/api-reference/metrics/daily), [GET /competitors](/de/api-reference/competitors/ranking), [GET /prompts](/de/api-reference/prompts/list) |
| Umwandeln | [PUT /v1/projects/\{projectId}](/de/api-reference/projects/update) mit `convertFromPitch` |