Skip to navigation

Export usage and costs

Use List Generation 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. 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.

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'
ParameterDescription
startTimeRequired. Start of the range, inclusive.
endTimeRequired. End of the range, exclusive. Must be after startTime.
limitItems per page, 1 to 500. Defaults to 100.
cursorThe 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.

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"])

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 needField
Generation IDgenerationId
TimecreatedAt, finishedAt
Modelmodel
StatusgenerationStatus
Billed quantitycomponents[].quantity with components[].unit (frames for lip sync, seconds for dubbing and speech)
Cost in USDtotalCostUsd, with each part in components[].amountUsd
Your ratecomponents[].unitRateUsd
API keyapiKey.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
{
"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.
  • 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.

availabilityMeaning
completeEvery component has an amount. totalCostUsd is set.
pendingNo amount is known yet and at least one is still being recorded. Read the item again later.
partialSome 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.
unavailableNo 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

StatusMeaningWhat to do
400A 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.
401Missing or invalid API key.See Authentication.
503 usage_dependency_unavailableRecorded 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.