> For the documentation index, fetch https://sync.so/docs/llms.txt. Append .md to a page URL for Markdown. Documentation-search MCP: https://sync.so/docs/_mcp/server.

# Exporta el uso y los costes

> Consulta el uso y los costes de un intervalo de fechas con una llamada a la API por página. Cada fila corresponde a una generación e incluye la hora, el modelo, el estado, los fotogramas facturados, el coste en usd y la clave de API que la creó.

Usa [Enumerar los costes de generación](/docs/api-reference/api/generate-api/list-costs) para consultar cuánto costaron tus generaciones en un intervalo de tiempo, por ejemplo para importar los datos cada día a un almacén de datos. Devuelve un elemento por generación finalizada, con hasta 500 por llamada. Un día con 8,000 generaciones requiere 16 solicitudes.

Para consultar el coste de una sola generación, usa [Obtener los costes de generación](/docs/api-reference/api/generate-api/get-costs). Ambos endpoints devuelven el mismo objeto de coste.

## Solicita un intervalo de tiempo

Envía `startTime` y `endTime` como fechas y horas UTC en formato ISO 8601. El intervalo filtra por el momento en que **terminó** la generación. `startTime` está incluido y `endTime` queda excluido.

```bash
curl --fail-with-body --silent --show-error --get \
  'https://api.sync.so/v2/usage/generations' \
  --header "x-api-key: $SYNC_API_KEY" \
  --data-urlencode 'startTime=2026-11-12T00:00:00Z' \
  --data-urlencode 'endTime=2026-11-13T00:00:00Z' \
  --data-urlencode 'limit=500'
```

| Parámetro   | Descripción                                                                                       |
| :---------- | :------------------------------------------------------------------------------------------------ |
| `startTime` | Obligatorio. Inicio del intervalo, incluido.                                                      |
| `endTime`   | Obligatorio. Fin del intervalo, excluido. Debe ser posterior a `startTime`.                       |
| `limit`     | Elementos por página, de 1 a 500. El valor predeterminado es 100.                                 |
| `cursor`    | El `nextCursor` de la página anterior. Envíalo con los mismos valores de `startTime` y `endTime`. |

Una clave de API enumera todas las generaciones de su organización, con independencia de la clave o del miembro de Studio que las creó.

## Lee todas las páginas

La respuesta es `{ "items": [...], "nextCursor": "..." }`. Solicita la página siguiente con los mismos valores de `startTime` y `endTime` y añade `cursor`. Repite hasta que `nextCursor` sea `null`. Los elementos se ordenan del más antiguo al más reciente.

```python
import os
import requests

def generation_costs(start_time: str, end_time: str):
    params = {"startTime": start_time, "endTime": end_time, "limit": 500}
    while True:
        response = requests.get(
            "https://api.sync.so/v2/usage/generations",
            headers={"x-api-key": os.environ["SYNC_API_KEY"]},
            params=params,
            timeout=60,
        )
        response.raise_for_status()
        page = response.json()
        yield from page["items"]
        if page["nextCursor"] is None:
            return
        params["cursor"] = page["nextCursor"]

for item in generation_costs("2026-11-12T00:00:00Z", "2026-11-13T00:00:00Z"):
    print(item["generationId"], item["finishedAt"], item["model"], item["totalCostUsd"])
```

```typescript
async function* generationCosts(startTime: string, endTime: string) {
  let cursor: string | null = null;
  do {
    const query = new URLSearchParams({ startTime, endTime, limit: "500" });
    if (cursor) query.set("cursor", cursor);
    const response = await fetch(
      `https://api.sync.so/v2/usage/generations?${query}`,
      { headers: { "x-api-key": process.env.SYNC_API_KEY! } },
    );
    if (!response.ok) throw new Error(await response.text());
    const page = await response.json();
    yield* page.items;
    cursor = page.nextCursor;
  } while (cursor);
}

for await (const item of generationCosts("2026-11-12T00:00:00Z", "2026-11-13T00:00:00Z")) {
  console.log(item.generationId, item.finishedAt, item.model, item.totalCostUsd);
}
```

Mantén `startTime` y `endTime` fijos al recorrer las páginas. El cursor continúa desde una generación del intervalo, así que cambiar el intervalo entre páginas puede omitir elementos. Si el cursor no corresponde a una generación del intervalo solicitado, se devuelve `400` para distinguir ese caso del fin de los datos.

## Qué contiene cada elemento

| Dato               | Campo                                                                                                                                                                                      |
| :----------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ID de generación   | `generationId`                                                                                                                                                                             |
| Hora               | `createdAt`, `finishedAt`                                                                                                                                                                  |
| Modelo             | `model`                                                                                                                                                                                    |
| Estado             | `generationStatus`                                                                                                                                                                         |
| Cantidad facturada | `components[].quantity` con `components[].unit` (`frames` para sincronización labial y `seconds` para doblaje y voz)                                                                       |
| Coste en USD       | `totalCostUsd`, con cada parte en `components[].amountUsd`                                                                                                                                 |
| Tu tarifa          | `components[].unitRateUsd`                                                                                                                                                                 |
| Clave de API       | `apiKey.name` y `apiKey.mask` (los primeros y últimos caracteres de la clave, como se muestran en Studio), además de `apiKey.id`. `apiKey` es `null` para una generación creada en Studio. |

```json
{
  "items": [
    {
      "generationId": "6bb46001-dd37-4f4d-908a-54bd67c4dc55",
      "generationStatus": "COMPLETED",
      "currency": "USD",
      "availability": "complete",
      "totalCostUsd": "0.79950",
      "knownSubtotalUsd": "0.79950",
      "retryAfterSeconds": null,
      "components": [
        {
          "type": "lipsync",
          "operationId": "6bb46001-dd37-4f4d-908a-54bd67c4dc55",
          "status": "recorded",
          "amountUsd": "0.79950",
          "credits": null,
          "valueBasis": "metered_usage",
          "quantity": 150,
          "unit": "frames",
          "unitRateUsd": "0.00533",
          "source": "recorded_usage",
          "reason": null
        }
      ],
      "excludedCosts": [
        "tax",
        "subscription_fees",
        "external_provider_charges",
        "account_level_adjustments"
      ],
      "createdAt": "2026-11-12T08:14:03.120Z",
      "finishedAt": "2026-11-12T08:15:41.007Z",
      "model": "sync-3",
      "apiKey": {
        "id": "6f4e5e34-399e-4e0d-82a2-f624a6ba9fd8",
        "name": "production",
        "mask": "sk-AB...wxyz"
      }
    }
  ],
  "nextCursor": "0d7f5b4e-2a1c-4c3e-9b8a-7e6d5c4b3a21"
}
```

Los importes son cadenas de números decimales con cinco cifras decimales. Interprétalos como valores decimales y evita usar números de coma flotante. Una generación con doblaje o voz generada tiene un componente por cada parte.

## Configura una extracción diaria

* **Usa intervalos consecutivos.** Cada generación aparece en un solo intervalo, aquel en el que terminó. Los intervalos como los días UTC nunca se solapan ni omiten generaciones.
* **Espera 10 minutos después de que termine el intervalo.** Los costes suelen registrarse en unos 10 minutos desde que termina la generación. Hasta entonces, un elemento puede tener `availability: "pending"`. Vuelve a leer el intervalo más tarde para recoger los importes registrados desde la última lectura.
* **Usa `generationId` como clave de cada fila.** Volver a leer un intervalo devuelve las mismas generaciones. Inserta las filas nuevas y actualiza las existentes para mantener la tabla al día.
* **Interpreta `null` como un valor desconocido, nunca como cero.** `totalCostUsd` es `null` si se desconoce alguna parte del coste. `knownSubtotalUsd` es la parte conocida. Consulta [Disponibilidad](#availability).
* **La lista solo incluye generaciones finalizadas.** Una generación en curso aparece en el intervalo en el que termina.

### Disponibilidad

`availability` indica qué parte del coste de un elemento se conoce. `status` y `reason` de cada componente indican por qué falta un importe.

| `availability` | Significado                                                                                                                                                                                                                                                                          |
| :------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `complete`     | Todos los componentes tienen un importe. `totalCostUsd` tiene un valor.                                                                                                                                                                                                              |
| `pending`      | Aún no se conoce ningún importe y queda al menos uno por registrar. Vuelve a leer el elemento más tarde.                                                                                                                                                                             |
| `partial`      | Algunos componentes tienen un importe y otros todavía carecen de él. `totalCostUsd` es `null`. `knownSubtotalUsd` es la suma de los importes conocidos. Un componente que falta puede estar pendiente o carecer de registro, como la voz generada que no se desglosa por generación. |
| `unavailable`  | No hay importes conocidos ni pendientes. Una generación fallida o rechazada no se cobra y normalmente carece de un coste registrado.                                                                                                                                                 |

Un componente `pending` suele recibir su importe en unos 10 minutos, aunque no hay garantía de que un elemento pase a `complete`. Los elementos `partial` y `unavailable` pueden conservar ese estado.

En los planes de créditos, los importes reflejan el valor nominal de \$0.01 por crédito, que puede diferir del precio pagado por los créditos. Los importes excluyen impuestos, cuotas de suscripción, reembolsos, créditos de la cuenta y cargos de proveedores externos.

## Gestiona los errores

| Estado                               | Significado                                                                                                                                                     | Qué hacer                                                       |
| :----------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------- |
| `400`                                | Fecha y hora ausentes o inválidas, intervalo vacío, `limit` fuera del rango de 1 a 500 o `cursor` que no corresponde a una generación del intervalo solicitado. | Corrige la solicitud.                                           |
| `401`                                | Clave de API ausente o inválida.                                                                                                                                | Consulta [Autenticación](/docs/api-reference/guides/authentication). |
| `503` `usage_dependency_unavailable` | No se pudo leer el uso registrado. Falla toda la página y no se devuelve una página parcial.                                                                    | Reintenta la misma solicitud.                                   |

Todas las solicitudes son de lectura, así que puedes volver a solicitar cualquier página con seguridad.