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

# Nutzung und Kosten exportieren

> Nutzung und Kosten für einen Zeitraum mit einem API-Aufruf pro Seite abrufen. Pro Generierung eine Zeile mit Zeit, Modell, Status, abgerechneten Frames, Kosten in USD und dem verwendeten API-Schlüssel.

Mit [List Generation Costs](/docs/api-reference/api/generate-api/list-costs) rufst du die Kosten deiner Generierungen für einen Zeitraum ab, etwa für einen täglichen Import in ein Data Warehouse. Der Endpunkt liefert einen Eintrag pro abgeschlossener Generierung und bis zu 500 Einträge pro Aufruf. Für einen Tag mit 8,000 Generierungen brauchst du daher 16 Anfragen.

Verwende [Get Generation Costs](/docs/api-reference/api/generate-api/get-costs), um die Kosten einer einzelnen Generierung abzurufen. Beide Endpunkte liefern dasselbe Kostenobjekt.

## Einen Zeitraum abfragen

Sende `startTime` und `endTime` als UTC-Zeitstempel nach ISO 8601. Der Zeitraum filtert nach dem Zeitpunkt, zu dem eine Generierung **abgeschlossen** wurde. `startTime` ist inklusive und `endTime` exklusive.

```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   | Beschreibung                                                                                                      |
| :---------- | :---------------------------------------------------------------------------------------------------------------- |
| `startTime` | Erforderlich. Beginn des Zeitraums, inklusive.                                                                    |
| `endTime`   | Erforderlich. Ende des Zeitraums, exklusive. Muss nach `startTime` liegen.                                        |
| `limit`     | Einträge pro Seite, 1 bis 500. Standardmäßig 100.                                                                 |
| `cursor`    | Der Wert von `nextCursor` aus der vorherigen Seite. Sende ihn mit denselben Werten für `startTime` und `endTime`. |

Mit einem API-Schlüssel kannst du alle Generierungen seiner Organisation auflisten. Es spielt keine Rolle, welcher Schlüssel oder welches Studio-Mitglied sie erstellt hat.

## Alle Seiten abrufen

Die Antwort lautet `{ "items": [...], "nextCursor": "..." }`. Fordere mit denselben Werten für `startTime` und `endTime` sowie mit `cursor` die nächste Seite an, bis `nextCursor` den Wert `null` hat. Die ältesten Einträge stehen zuerst.

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

Lass `startTime` und `endTime` beim Abrufen weiterer Seiten unverändert. Der Cursor setzt bei einer Generierung innerhalb des Zeitraums an. Wenn du den Zeitraum zwischen Seiten änderst, kannst du Einträge überspringen. Wenn der Cursor nicht auf eine Generierung im angefragten Zeitraum verweist, meldet die API `400`. So lässt sich der Fehler vom Ende der Liste unterscheiden.

## Angaben pro Eintrag

| Angabe                 | Feld                                                                                                                                                                                              |
| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Generierungs-ID        | `generationId`                                                                                                                                                                                    |
| Zeit                   | `createdAt`, `finishedAt`                                                                                                                                                                         |
| Modell                 | `model`                                                                                                                                                                                           |
| Status                 | `generationStatus`                                                                                                                                                                                |
| Abgerechnete Menge     | `components[].quantity` mit `components[].unit` (`frames` für Lip Sync, `seconds` für Dubbing und Sprache)                                                                                        |
| Kosten in USD          | `totalCostUsd` und die einzelnen Beträge in `components[].amountUsd`                                                                                                                              |
| Dein Preis pro Einheit | `components[].unitRateUsd`                                                                                                                                                                        |
| API-Schlüssel          | `apiKey.name` und `apiKey.mask` (die ersten und letzten Zeichen des Schlüssels wie in Studio angezeigt) sowie `apiKey.id`. Bei einer in Studio erstellten Generierung ist `apiKey` gleich `null`. |

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

Beträge sind Zeichenfolgen mit fünf Dezimalstellen. Lies sie als Dezimalzahlen ein und vermeide Gleitkommazahlen. Eine Generierung mit Dubbing oder erzeugter Sprache enthält eine Komponente pro Bestandteil.

## Einen täglichen Abruf einrichten

* **Verwende lückenlos aufeinanderfolgende Zeiträume.** Jede Generierung erscheint genau in dem Zeitraum, in dem sie abgeschlossen wurde. Wenn du zum Beispiel einen Zeitraum pro UTC-Tag verwendest, überschneiden sich die Zeiträume nie und keine Generierung wird übersprungen.
* **Warte nach dem Ende des Zeitraums 10 Minuten.** Kosten werden normalerweise innerhalb von etwa 10 Minuten nach Abschluss erfasst. Davor kann ein Eintrag `availability: "pending"` haben. Rufe den Zeitraum später erneut ab, um inzwischen erfasste Beträge zu übernehmen.
* **Verwende `generationId` als Zeilenschlüssel.** Ein erneuter Abruf desselben Zeitraums liefert dieselben Generierungen. Füge neue Zeilen ein und aktualisiere bestehende, damit deine Tabelle korrekt bleibt.
* **Behandle `null` als unbekannten Wert.** `totalCostUsd` ist `null`, sofern nicht alle Kostenbestandteile bekannt sind. `knownSubtotalUsd` enthält den bekannten Teil. Siehe [Verfügbarkeit](#availability).
* **Die Liste enthält nur abgeschlossene Generierungen.** Eine laufende Generierung erscheint im Zeitraum, in dem sie abgeschlossen wird.

### Verfügbarkeit

`availability` gibt an, wie viel von den Kosten eines Eintrags bekannt ist. `status` und `reason` der einzelnen Komponenten geben an, warum ein Betrag fehlt.

| `availability` | Bedeutung                                                                                                                                                                                                                                                                                                 |
| :------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `complete`     | Für jede Komponente liegt ein Betrag vor. `totalCostUsd` ist gesetzt.                                                                                                                                                                                                                                     |
| `pending`      | Es ist noch kein Betrag bekannt und mindestens einer wird noch erfasst. Rufe den Eintrag später erneut ab.                                                                                                                                                                                                |
| `partial`      | Für einige Komponenten liegt ein Betrag vor. `totalCostUsd` ist `null` und `knownSubtotalUsd` ist die Summe der bekannten Beträge. Bei einer fehlenden Komponente kann die Erfassung noch ausstehen oder es gibt keinen Datensatz, etwa wenn erzeugte Sprache nicht pro Generierung aufgeschlüsselt wird. |
| `unavailable`  | Es ist kein Betrag bekannt und keiner steht aus. Fehlgeschlagene oder abgelehnte Generierungen werden nicht berechnet und haben normalerweise keinen Kosteneintrag.                                                                                                                                       |

Bei einer Komponente mit `pending` liegt der Betrag meist innerhalb von etwa 10 Minuten vor. Es gibt jedoch keine Garantie, dass der Eintrag `complete` wird. Einträge mit `partial` oder `unavailable` können diesen Status behalten.

Bei Credit-Tarifen entsprechen die Beträge dem Nennwert von \$0.01 pro Credit. Dieser Wert kann vom tatsächlich gezahlten Preis abweichen. Steuern, Abogebühren, Erstattungen, Kontoguthaben und Gebühren externer Anbieter sind in den Beträgen nicht enthalten.

## Fehler behandeln

| Status                               | Bedeutung                                                                                                                                                                          | Was du tun kannst                                                |
| :----------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------- |
| `400`                                | Ein fehlender oder ungültiger Zeitstempel, ein leerer Zeitraum, ein `limit` außerhalb von 1 bis 500 oder ein `cursor`, der auf keine Generierung im angefragten Zeitraum verweist. | Korrigiere die Anfrage.                                          |
| `401`                                | Der API-Schlüssel fehlt oder ist ungültig.                                                                                                                                         | Siehe [Authentifizierung](/docs/api-reference/guides/authentication). |
| `503` `usage_dependency_unavailable` | Die erfasste Nutzung ließ sich nicht lesen. Die gesamte Seite schlägt fehl und es wird keine unvollständige Seite zurückgegeben.                                                   | Wiederhole dieselbe Anfrage.                                     |

Jede Anfrage liest Daten. Du kannst den Abruf jeder Seite gefahrlos wiederholen.