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

# Export usage and costs

> Load usage and cost for a date range with one API call per page. One row per generation with time, model, status, billed frames, cost in usd, and the API key that made it.

Use [List Generation Costs](/docs/api-reference/api/generate-api/list-costs) to load what your generations cost over a time range, for example a daily pull into a data warehouse. It returns one item per finished generation, up to 500 per call, so a day with 8,000 generations is 16 requests.

For the cost of a single generation, use [Get Generation Costs](/docs/api-reference/api/generate-api/get-costs). Both endpoints return the same cost object.

## Request a time range

Send `startTime` and `endTime` as UTC ISO 8601 date-times. The range filters on when a generation **finished**. `startTime` is inclusive and `endTime` is exclusive.

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

| Parameter   | Description                                                                               |
| :---------- | :---------------------------------------------------------------------------------------- |
| `startTime` | Required. Start of the range, inclusive.                                                  |
| `endTime`   | Required. End of the range, exclusive. Must be after `startTime`.                         |
| `limit`     | Items per page, 1 to 500. Defaults to 100.                                                |
| `cursor`    | The `nextCursor` from the previous page. Send it with the same `startTime` and `endTime`. |

An API key lists every generation in its organization, whichever key or Studio member created it.

## Read every page

The response is `{ "items": [...], "nextCursor": "..." }`. Request the next page with the same `startTime` and `endTime` plus `cursor`, until `nextCursor` is `null`. Items are ordered oldest first.

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

Keep `startTime` and `endTime` unchanged while you page. A cursor continues from one generation in the range, so changing the range between pages can skip items. A cursor that is not a generation in the requested range returns `400`, so it can't be mistaken for the end of the data.

## What each item contains

| What you need   | Field                                                                                                                                                                |
| :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Generation ID   | `generationId`                                                                                                                                                       |
| Time            | `createdAt`, `finishedAt`                                                                                                                                            |
| Model           | `model`                                                                                                                                                              |
| Status          | `generationStatus`                                                                                                                                                   |
| Billed quantity | `components[].quantity` with `components[].unit` (`frames` for lip sync, `seconds` for dubbing and speech)                                                           |
| Cost in USD     | `totalCostUsd`, with each part in `components[].amountUsd`                                                                                                           |
| Your rate       | `components[].unitRateUsd`                                                                                                                                           |
| API key         | `apiKey.name` and `apiKey.mask` (the first and last characters of the key, as shown in Studio), plus `apiKey.id`; `apiKey` is `null` for a generation made in 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"
}
```

Amounts are decimal strings with five decimal places. Parse them as decimals, not floats. A generation with dubbing or generated speech has one component for each part.

## Build a daily pull

* **Use back-to-back ranges.** A generation appears in exactly one range, the one in which it finished. Ranges such as one per UTC day never overlap and never skip a generation.
* **Wait 10 minutes after the range ends.** Costs are normally recorded within about 10 minutes of completion. Before that an item can have `availability: "pending"`. Read the range again later to pick up amounts recorded since.
* **Key your rows on `generationId`.** Reading a range again returns the same generations, so an upsert keeps your table correct.
* **Treat `null` as unknown, not zero.** `totalCostUsd` is `null` unless every part of the cost is known. `knownSubtotalUsd` is the known portion. See [availability](#availability).
* **Only finished generations are listed.** A generation still in progress appears in the range in which it finishes.

### Availability

`availability` says how much of an item's cost is known. Each component's `status` and `reason` say why an amount is missing.

| `availability` | Meaning                                                                                                                                                                                                                                            |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `complete`     | Every component has an amount. `totalCostUsd` is set.                                                                                                                                                                                              |
| `pending`      | No amount is known yet and at least one is still being recorded. Read the item again later.                                                                                                                                                        |
| `partial`      | Some components have an amount and others don't. `totalCostUsd` is `null`; `knownSubtotalUsd` is the sum of the known ones. A missing component can be pending or have no record, for example generated speech that isn't itemized per generation. |
| `unavailable`  | No amount is known and none is pending. A failed or rejected generation is not charged and normally has no cost on record.                                                                                                                         |

A `pending` component usually gets its amount within about 10 minutes, but an item is not guaranteed to become `complete`. `partial` and `unavailable` items can stay that way.

On credit plans, amounts are the credits' face value of \$0.01 each, which can differ from the cash price paid for those credits. Amounts exclude tax, subscription fees, refunds, account credits, and external provider charges.

## Handle errors

| Status                               | Meaning                                                                                                                                    | What to do                                                  |
| :----------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------- |
| `400`                                | A missing or invalid date-time, an empty range, a `limit` outside 1 to 500, or a `cursor` that is not a generation in the requested range. | Fix the request.                                            |
| `401`                                | Missing or invalid API key.                                                                                                                | See [Authentication](/docs/api-reference/guides/authentication). |
| `503` `usage_dependency_unavailable` | Recorded usage could not be read. The page fails as a whole; no partial page is returned.                                                  | Retry the same request.                                     |

Every request is a read, so any page is safe to retry.