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

# Exportar uso e custos

> Carregar uso e custos para um intervalo de datas com uma chamada API por página. Uma linha por geração com tempo, modelo, status, quadros cobrados e custo em USD, e a chave de API que gerou isso.

Use [Custos de Geração de Listas](/docs/api-reference/api/generate-api/list-costs) Para carregar o que suas gerações custam ao longo de um intervalo de tempo, por exemplo, um diariamente puxar em um depósito de dados. 500 Por chamada, então um dia com 8,000 As gerações são 16 Pedidos.

Para o custo de uma única geração, use [Obter Custos de Geração](/docs/api-reference/api/generate-api/get-costs). Ambos os endpoints retornam o mesmo objeto de custo.

## Solicitar um intervalo de tempo

Envie `startTime` e `endTime` como datas-hora ISO 8601 UTC. O intervalo filtra pelo momento em que uma geração **concluiu**. `startTime` é inclusivo e `endTime` é exclusivo.

```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   | Descrição                                                                     |
| :---------- | :---------------------------------------------------------------------------- |
| `startTime` | Obrigatório. Início do intervalo, inclusivo.                                  |
| `endTime`   | Obrigatório. Fim do intervalo, exclusivo. Deve ser após `startTime`.          |
| `limit`     | Número de itens por página, de 1 a 500. Padrão é 100.                         |
| `cursor`    | O `nextCursor` da página anterior. Envie com o mesmo `startTime` e `endTime`. |

Uma chave de API lista todas as gerações da organização, independentemente de qual chave ou membro do Studio as criou.

## Leia todas as páginas

A resposta é `{ "items": [...], "nextCursor": "..." }`. Solicite a próxima página com o mesmo `startTime` e `endTime` mais `cursor`, até que `nextCursor` seja `null`. Os itens estão ordenados do mais antigo para o mais recente.

```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);
}
```

Mantenha `startTime` e `endTime` ao consultar as páginas seguintes. O cursor retoma a consulta a partir de uma geração do intervalo. Alterar o intervalo entre páginas pode fazer com que alguns itens sejam ignorados. Se o cursor não corresponder a uma geração do intervalo solicitado, a API retorna `400`, o que diferencia esse erro do fim dos resultados.

## O que cada item contém

| O que você precisa | Campo                                                                                                                                                                             |
| :----------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ID da geração      | `generationId`                                                                                                                                                                    |
| Tempo              | `createdAt`, `finishedAt`                                                                                                                                                         |
| Modelo             | `model`                                                                                                                                                                           |
| Status             | `generationStatus`                                                                                                                                                                |
| Quantidade cobrada | `components[].quantity` com `components[].unit` (`frames` para sincronização labial, `seconds` para dublagem e falas)                                                             |
| Custo em USD       | `totalCostUsd`, com cada parte em `components[].amountUsd`                                                                                                                        |
| Sua taxa           | `components[].unitRateUsd`                                                                                                                                                        |
| Chave API          | `apiKey.name` e `apiKey.mask` (os primeiros e os últimos caracteres da chave, como exibidos no Studio), além de `apiKey.id`. `apiKey` é `null` para uma geração criada no 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"
}
```

Os valores são strings decimais com cinco casas decimais. Analisá-los como decimais, não como flutuantes. Uma geração com dublagem ou com texto gerado tem um componente para cada parte.

## Crie uma extração diária

* **Use faixas consecutivas.** Uma geração aparece exatamente em uma faixa, a faixa em que ela foi concluída. As faixas, como uma por dia UTC, nunca se sobrepõem e nunca deixam de incluir uma geração.
* **Espere 10 minutos após o fim do intervalo.** Os custos são normalmente registrados dentro de cerca de 10 minutos após a conclusão. Antes disso, um item pode ter `availability: "pending"`. Leia o intervalo novamente mais tarde para capturar as quantias registradas desde então.
* **Use `generationId` como chave para suas linhas.** Ao ler uma faixa novamente, você recebe as mesmas gerações, então uma atualização de inserção garante que sua tabela esteja correta.
* **Trate `null` como desconhecido, não como zero.** `totalCostUsd` é `null` a menos que todos os componentes do custo sejam conhecidos. `knownSubtotalUsd` é a parte conhecida. Veja [disponibilidade](#availability).
* **Somente as gerações concluídas são listadas.** Uma geração em progresso aparece na faixa em que ela é concluída.

### Disponibilidade

`availability` diz quantas partes do custo de um item são conhecidas. Cada componente tem `status` e `reason` que explicam por que uma quantia está faltando.

| `availability` | Significado                                                                                                                                                                                                                                                |
| :------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `complete`     | Cada componente tem uma quantidade. `totalCostUsd` está definido.                                                                                                                                                                                          |
| `pending`      | Nenhuma quantidade é conhecida ainda e pelo menos uma está sendo registrada. Leia o item novamente mais tarde.                                                                                                                                             |
| `partial`      | Alguns componentes têm uma quantidade e outros não. `totalCostUsd` é `null`; `knownSubtotalUsd` é a soma das conhecidas. Um componente ausente pode estar pendente ou não ter registro, por exemplo, uma geração de áudio que não é itemizada por geração. |
| `unavailable`  | Não se conhece nenhuma quantidade e nenhum está pendente. Uma geração falhada ou rejeitada não é cobrada e normalmente não tem registro de custo.                                                                                                          |

Um componente `pending` geralmente recebe sua quantidade dentro de cerca de 10 minutos, mas um item não está garantido a se tornar `complete`. Itens `partial` e `unavailable` podem permanecer assim.

Nos planos de crédito, os valores são o valor nominal dos créditos da \$0.01 cada, que pode diferir do preço pago em dinheiro por esses créditos.

## Tratar erros

| Status                               | Significado                                                                                                                                                   | O que fazer                                               |
| :----------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------- |
| `400`                                | Uma data-hora ausente ou inválida, um intervalo vazio, um `limit` fora do intervalo de 1 a 500, ou um `cursor` que não é uma geração no intervalo solicitado. | Corrija a solicitação.                                    |
| `401`                                | Chave API ausente ou inválida.                                                                                                                                | Ver [Autenticação](/docs/api-reference/guides/authentication). |
| `503` `usage_dependency_unavailable` | O uso registrado não pode ser lido. A página falha como um todo; nenhuma página parcial é retornada.                                                          | Tente a mesma solicitação novamente.                      |

Todo pedido é uma leitura, então qualquer página pode ser reenviada.