Automatizza un pitch

Le agenzie ripetono la stessa sequenza per ogni prospect: creare un progetto pitch, scegliere i modelli AI, aggiungere i prompt, leggere i risultati qualche giorno dopo e — se il prospect firma — convertire il pitch in un progetto cliente. Ogni passaggio è disponibile tramite la REST API, con esattamente gli stessi limiti e codici di errore della dashboard, così un pitch può essere avviato da un CRM, da un form o da uno script senza che nessuno apra la UI.

I progetti pitch richiedono un account Agency. Non hanno costo di progetto, sono limitati a 50 prompt e vengono sospesi automaticamente alla chiusura della finestra del pitch (1, 7 o 14 giorni). Il numero di progetti pitch contemporanei è limitato per pacchetto.

1. Crea il progetto pitch

language è obbligatorio e determina la lingua dei prompt e il filtro paese. Un nuovo progetto parte con i modelli predefiniti del tuo account.

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
  }'

La risposta contiene l’id necessario per tutte le chiamate successive e i models correnti. Un 403 con details.reason = "pitch_project_limit" significa che tutti gli slot pitch del tuo pacchetto sono occupati — converti o elimina prima un pitch.

2. Imposta i modelli

I prompt vengono sempre eseguiti sui modelli del progetto, quindi impostali prima di aggiungere i prompt. Questa chiamata sostituisce l’intero set, esattamente come la pagina Impostazioni modelli.

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"]}'

Un 403 con details.reason = "agency_limit" significa che le risposte AI mensili previste superano la fascia inclusa nel tuo pacchetto (details.nextPackage indica l’upgrade). Sul pacchetto più alto la chiamata riesce e restituisce invece un meteredNotice; l’eccedenza viene fatturata come consumo extra.

3. Aggiungi i prompt

Ometti models per usare i modelli del progetto. language usa come predefinita la lingua del progetto. Ogni prompt viene messo in coda immediatamente (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()

Possibili motivi di 403: pitch_prompt_limit (raggiunti i 50 prompt), pitch_expired, agency_limit. Passare un modello non abilitato sul progetto restituisce 400 model_not_enabled — torna al passaggio 2.

4. Leggi i risultati

Concedi ai worker qualche minuto per le prime risposte; un pitch completo ha di solito un’esecuzione al giorno. Poi leggi i KPI, il ranking dei concorrenti e il dettaglio per prompt relativi alla finestra del pitch:

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 e citationRate sono spiegati in KPI e metriche. Filtra per un singolo motore con model=<id>, usando uno dei models del progetto.

5. Converti un pitch vinto

Trasforma il pitch in un progetto cliente fatturabile: rimuove il limite di prompt, disattiva la sospensione automatica e riattiva tutto ciò che la scadenza aveva sospeso.

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}'

Un 403 con details.reason = "agency_limit" e details.limit = "projects" significa che nessuno slot cliente è libero; con details.limit = "answers" i prompt del progetto supererebbero la fascia di risposte inclusa al prezzo del mese intero.

Endpoint utilizzati

Passaggio	Endpoint
Crea il pitch	POST /v1/projects
Imposta i modelli	PUT /v1/projects/{projectId}
Aggiungi i prompt	POST /v1/projects/{projectId}/prompts
Leggi i risultati	GET /metrics, GET /competitors, GET /prompts
Converti	PUT /v1/projects/{projectId} con `convertFromPitch`

Guides

Projects

Prompts

Metrics

Competitors

Sources

Tags

Fan-outs

Tasks

Export

Attribution

Automatizza un pitch

Automatizza un pitch

1. Crea il progetto pitch

2. Imposta i modelli

3. Aggiungi i prompt

4. Leggi i risultati

5. Converti un pitch vinto

Endpoint utilizzati

​Automatizza un pitch

​1. Crea il progetto pitch

​2. Imposta i modelli

​3. Aggiungi i prompt

​4. Leggi i risultati

​5. Converti un pitch vinto

​Endpoint utilizzati

Automatizza un pitch

1. Crea il progetto pitch

2. Imposta i modelli

3. Aggiungi i prompt

4. Leggi i risultati

5. Converti un pitch vinto

Endpoint utilizzati