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

# Exporter l’utilisation et les coûts

> Récupérez l’utilisation et les coûts sur une période, avec un appel API par page et une ligne par génération indiquant la date, le modèle, l’état, les images facturées, le coût en USD et la clé API utilisée.

Utilisez [Lister les coûts des générations](/docs/api-reference/api/generate-api/list-costs) pour récupérer le coût de vos générations sur une période, par exemple pour alimenter chaque jour un entrepôt de données. L’API renvoie un élément par génération terminée et jusqu’à 500 par appel. Il faut donc 16 requêtes pour une journée de 8,000 générations.

Pour connaître le coût d’une seule génération, utilisez [Récupérer les coûts d’une génération](/docs/api-reference/api/generate-api/get-costs). Les deux points de terminaison renvoient le même objet de coût.

## Interroger une période

Envoyez `startTime` et `endTime` sous forme de dates et heures UTC au format ISO 8601. Le filtre porte sur la date de **fin** de la génération. La borne `startTime` est incluse et la borne `endTime` est exclue.

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

| Paramètre   | Description                                                                                           |
| :---------- | :---------------------------------------------------------------------------------------------------- |
| `startTime` | Obligatoire. Début inclus de la période.                                                              |
| `endTime`   | Obligatoire. Fin exclue de la période. Doit être postérieure à `startTime`.                           |
| `limit`     | Éléments par page, de 1 à 500. La valeur par défaut est 100.                                          |
| `cursor`    | Le `nextCursor` de la page précédente. Envoyez-le avec les mêmes valeurs de `startTime` et `endTime`. |

Une clé API permet de lister toutes les générations de son organisation, quelle que soit la clé ou la personne qui les a créées dans Studio.

## Lire toutes les pages

La réponse est `{ "items": [...], "nextCursor": "..." }`. Demandez la page suivante avec les mêmes valeurs de `startTime` et `endTime`, ainsi que `cursor`, jusqu’à ce que `nextCursor` vaille `null`. Les éléments sont triés du plus ancien au plus récent.

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

Conservez les valeurs de `startTime` et `endTime` pendant la pagination. Le curseur reprend à partir d’une génération de la période. Changer de période entre deux pages peut donc omettre des éléments. Si le curseur ne correspond à aucune génération de la période demandée, l’API renvoie `400` pour distinguer cette erreur de la fin des données.

## Contenu de chaque élément

| Donnée                    | Champ                                                                                                                                                                                            |
| :------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Identifiant de génération | `generationId`                                                                                                                                                                                   |
| Date et heure             | `createdAt`, `finishedAt`                                                                                                                                                                        |
| Modèle                    | `model`                                                                                                                                                                                          |
| État                      | `generationStatus`                                                                                                                                                                               |
| Quantité facturée         | `components[].quantity` avec `components[].unit` (`frames` pour la synchronisation labiale, `seconds` pour le doublage et la synthèse vocale)                                                    |
| Coût en USD               | `totalCostUsd`, avec le détail dans `components[].amountUsd`                                                                                                                                     |
| Votre tarif               | `components[].unitRateUsd`                                                                                                                                                                       |
| Clé API                   | `apiKey.name` et `apiKey.mask` (les premiers et derniers caractères de la clé, tels qu’affichés dans Studio), ainsi que `apiKey.id`. `apiKey` vaut `null` pour une génération créée dans 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"
}
```

Les montants sont des chaînes représentant des nombres à cinq décimales. Analysez-les comme des nombres décimaux et excluez les nombres à virgule flottante. Une génération avec doublage ou synthèse vocale contient une composante pour chaque prestation.

## Mettre en place un export quotidien

* **Utilisez des périodes consécutives.** Une génération apparaît dans une seule période, celle où elle s’est terminée. Les périodes définies par jour UTC, par exemple, ne se chevauchent pas et n’omettent aucune génération.
* **Attendez 10 minutes après la fin de la période.** L’enregistrement des coûts prend généralement environ 10 minutes après la fin de la génération. Avant cela, un élément peut avoir `availability: "pending"`. Interrogez à nouveau la période plus tard pour récupérer les montants enregistrés depuis.
* **Utilisez `generationId` comme clé de ligne.** Relire une période renvoie les mêmes générations. Insérez ou mettez à jour les lignes selon leur clé pour garder votre table à jour.
* **Interprétez `null` comme un montant inconnu.** `totalCostUsd` vaut `null` tant que toutes les composantes du coût ne sont pas connues. `knownSubtotalUsd` indique la part connue. Consultez [Disponibilité](#availability).
* **La liste contient uniquement les générations terminées.** Une génération en cours apparaît dans la période où elle se termine.

### Disponibilité

`availability` indique la part connue du coût d’un élément. Les champs `status` et `reason` de chaque composante indiquent pourquoi un montant manque.

| `availability` | Signification                                                                                                                                                                                                                                                                                           |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `complete`     | Toutes les composantes ont un montant. `totalCostUsd` est renseigné.                                                                                                                                                                                                                                    |
| `pending`      | Aucun montant n’est encore connu et au moins un montant est en cours d’enregistrement. Relisez l’élément plus tard.                                                                                                                                                                                     |
| `partial`      | Certaines composantes ont un montant et d’autres non. `totalCostUsd` vaut `null` et `knownSubtotalUsd` est la somme des montants connus. Une composante manquante peut être en cours d’enregistrement ou sans montant enregistré, par exemple si la synthèse vocale n’est pas détaillée par génération. |
| `unavailable`  | Aucun montant n’est connu ni en cours d’enregistrement. Une génération qui échoue ou est rejetée n’est pas facturée et n’a généralement aucun coût enregistré.                                                                                                                                          |

Le montant d’une composante `pending` est généralement renseigné dans un délai d’environ 10 minutes. Rien ne garantit qu’un élément passera à `complete`. Les éléments `partial` et `unavailable` peuvent conserver cet état.

Avec les forfaits à crédits, les montants correspondent à la valeur nominale de \$0.01 par crédit. Cette valeur peut différer du prix payé. Les montants excluent les taxes, les frais d’abonnement, les remboursements, les avoirs et les frais des prestataires externes.

## Gérer les erreurs

| Statut                               | Signification                                                                                                                                                                      | Action                                                              |
| :----------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------ |
| `400`                                | Une date ou heure manquante ou invalide, une période vide, un `limit` hors de l’intervalle de 1 à 500 ou un `cursor` qui ne correspond à aucune génération de la période demandée. | Corrigez la requête.                                                |
| `401`                                | Clé API manquante ou invalide.                                                                                                                                                     | Consultez [Authentification](/docs/api-reference/guides/authentication). |
| `503` `usage_dependency_unavailable` | Impossible de lire l’utilisation enregistrée. La requête échoue pour la page entière. Elle ne renvoie aucune page partielle.                                                       | Réessayez avec la même requête.                                     |

Toutes les requêtes sont en lecture seule. Vous pouvez donc réessayer de récupérer n’importe quelle page sans risque.