> ## 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.

# Automatizar un pitch

> Crea un proyecto pitch, establece sus modelos, añade prompts, lee los resultados y convierte un pitch ganado — el flujo completo de agencia en cinco llamadas a la API.

# Automatizar un pitch

Las agencias repiten la misma secuencia con cada prospecto: crear un proyecto
pitch, elegir los modelos de IA, añadir los prompts, leer los resultados unos
días después y — si el prospecto firma — convertir el pitch en un proyecto de
cliente. Cada paso está disponible a través de la API REST, con exactamente los
mismos límites y códigos de error que el dashboard, de modo que un pitch puede
iniciarse desde un CRM, un formulario o un script sin que nadie abra la UI.

<Info>
  Los proyectos pitch requieren una cuenta **Agency**. No tienen coste de
  proyecto, están limitados a **50 prompts** y se pausan automáticamente al
  cerrarse la ventana del pitch (1, 7 o 14 días). El número de proyectos pitch
  simultáneos está limitado por paquete.
</Info>

## 1. Crear el proyecto pitch

`language` es obligatorio y determina el idioma de los prompts y el filtro de
país. Un proyecto nuevo empieza con los modelos predeterminados de tu cuenta.

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

La respuesta contiene el `id` que necesitas para todas las llamadas siguientes
y los `models` actuales. Un `403` con `details.reason = "pitch_project_limit"`
significa que todos los slots de pitch de tu paquete están en uso — convierte o
elimina un pitch primero.

## 2. Establecer los modelos

Los prompts siempre se ejecutan en los modelos del proyecto, así que
establécelos **antes** de añadir prompts. Esto reemplaza el conjunto completo,
igual que hace la página Model Settings.

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

Un `403` con `details.reason = "agency_limit"` significa que las respuestas de
IA mensuales proyectadas superan la franja incluida en tu paquete
(`details.nextPackage` indica el upgrade). En el paquete superior la llamada
tiene éxito y devuelve en su lugar un `meteredNotice`; el exceso se factura
como consumo adicional.

## 3. Añadir los prompts

Omite `models` para usar los modelos del proyecto. `language` usa por defecto
el idioma del proyecto. Cada prompt se pone en cola de inmediato
(`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()
```

Posibles motivos de `403`: `pitch_prompt_limit` (50 prompts alcanzados),
`pitch_expired`, `agency_limit`. Pasar un modelo que no está habilitado en el
proyecto devuelve `400 model_not_enabled` — vuelve al paso 2.

## 4. Leer los resultados

Da a los workers unos minutos para las primeras respuestas; un pitch completo
suele tener una ejecución al día. Después lee los KPIs, el ranking de
competidores y el desglose por prompt para la ventana del pitch:

```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` y `citationRate` se explican en
[KPIs explicados](/es/getting-started/kpis). Filtra por un único motor con
`model=<id>`, usando uno de los `models` del proyecto.

## 5. Convertir un pitch ganado

Convierte el pitch en un proyecto de cliente facturable: elimina el máximo de
prompts, detiene la pausa automática y reanuda todo lo que la caducidad haya
pausado.

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

Un `403` con `details.reason = "agency_limit"` y `details.limit = "projects"`
significa que no hay ningún slot de cliente libre; con `details.limit = "answers"`
los prompts del proyecto superarían la franja de respuestas incluida al precio
de mes completo.

## Endpoints utilizados

| Paso               | Endpoint                                                                                                                                                   |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Crear pitch        | [POST /v1/projects](/es/api-reference/projects/create)                                                                                                     |
| Establecer modelos | [PUT /v1/projects/\{projectId}](/es/api-reference/projects/update)                                                                                         |
| Añadir prompts     | [POST /v1/projects/\{projectId}/prompts](/es/api-reference/prompts/add)                                                                                    |
| Leer resultados    | [GET /metrics](/es/api-reference/metrics/daily), [GET /competitors](/es/api-reference/competitors/ranking), [GET /prompts](/es/api-reference/prompts/list) |
| Convertir          | [PUT /v1/projects/\{projectId}](/es/api-reference/projects/update) con `convertFromPitch`                                                                  |