Usage API

De Usage API retourneert de historische API-taken van je team, samen met de credits die elke taak heeft verbruikt. Filter op tijdvenster, endpoint of status, en blader door de resultaten om ze in bulk te exporteren.

Beschikbaarheid. De API-sleutel moet toebehoren aan een team met een Studio- of Enterprise-abonnement; sleutels van elk ander abonnement, of zonder team, krijgen een 403.

GET/openapi/v1/usage/tasks

List Usage Records

Retourneert één pagina met de API-taken van het team, nieuwste eerst. Zonder expliciet tijdsbereik omvat de respons de laatste 30 dagen.

Parameters

  • Name
    page_num
    Type
    integer
    standaard 1
    Description

    Paginanummer voor paginering.

  • Name
    page_size
    Type
    integer
    standaard 10
    Description

    Limiet voor paginagrootte. Maximaal toegestaan is 100 items.

  • Name
    sort_by
    Type
    string
    standaard -created_at
    Description

    Veld om op te sorteren.

    Beschikbare waarden:

    • +created_at: Sorteer op aanmaaktijd in oplopende volgorde.
    • -created_at: Sorteer op aanmaaktijd in aflopende volgorde.
  • Name
    start_time
    Type
    string
    Description

    Begin van het created_at-venster, als een RFC 3339-tijdstempel (bijv. 2026-08-01T00:00:00Z). Standaard 30 dagen vóór end_time. Het venster kan maximaal 1 jaar beslaan — blader voor grotere exports door opeenvolgende vensters.

  • Name
    end_time
    Type
    string
    Description

    Einde van het created_at-venster, als een RFC 3339-tijdstempel. Standaard de huidige tijd.

  • Name
    endpoints
    Type
    string
    Description

    Kommagescheiden lijst van endpointnamen om op te nemen. Accepteert dezelfde waarden die het endpoint-veld in de respons bevat — text-to-3d, text-to-3d-preview, text-to-3d-refine, image-to-3d, multi-image-to-3d, retexture, remesh, convert, resize, uv-unwrap, rig, animate, text-to-motion, text-to-image, image-to-image, print-multi-color, print-repair, print-analyze — waarbij text-to-3d een overkoepelende term is die zowel de preview- als de refine-fase omvat. Weglaten om alle endpoints op te nemen.

  • Name
    status
    Type
    string
    Description

    Filter op eindstatus van de taak: SUCCEEDED of FAILED. Weglaten om beide op te nemen.

Retourneert

Retourneert een gepagineerde lijst van The Usage Record Objects.

Records omvatten taken die een eindstatus hebben bereikt. Credits worden in rekening gebracht wanneer een taak wordt aangemaakt, dus een taak die nog draait op het moment van exporteren staat nog niet in de resultaten van dat venster — haal recente vensters opnieuw op (of exporteer met een korte vertraging) als je totalen exact moeten overeenkomen met je credit-saldo.

Teams met een aangepast dataretentiebeleid ontvangen records binnen hun geconfigureerde retentievenster.

Request

GET
/openapi/v1/usage/tasks
curl "https://api.meshy.ai/openapi/v1/usage/tasks?page_size=50&start_time=2026-08-01T00:00:00Z&end_time=2026-09-01T00:00:00Z" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "endpoint": "image-to-3d",
    "status": "SUCCEEDED",
    "created_at": 1755787000000,
    "finished_at": 1755787045000,
    "consumed_credits": 20,
    "api_key_name": "production",
    "api_key_suffix": "a1b2"
  },
  {
    "task_id": "018a210d-1c22-7e0f-9d3a-4a5b6c7d8e9f",
    "endpoint": "text-to-3d-refine",
    "status": "FAILED",
    "created_at": 1755786000000,
    "finished_at": 1755786030000,
    "consumed_credits": 0,
    "api_key_name": "production",
    "api_key_suffix": "a1b2"
  }
]

The Usage Record Object

  • Name
    task_id
    Type
    string
    Description

    ID van de taak die dit record factureert — dezelfde ID die het aanmakende endpoint teruggaf. Om de taak zelf op te halen (inclusief het uitvoermodel of de afbeeldings-URL's, bij elke leesbewerking opnieuw ondertekend), geef je deze door aan het bijbehorende ophaal-endpoint, bijv. GET /openapi/v1/{endpoint}/{task_id}.

  • Name
    endpoint
    Type
    string
    Description

    Het endpoint waarop de taak is uitgevoerd, bijv. image-to-3d of text-to-3d-refine. Tekst naar 3D-taken rapporteren hun fase (text-to-3d-preview / text-to-3d-refine).

  • Name
    status
    Type
    string
    Description

    Eindstatus van de taak: SUCCEEDED of FAILED.

  • Name
    created_at
    Type
    timestamp
    Description

    Tijdstempel van het aanmaken van de taak, in milliseconden.

  • Name
    finished_at
    Type
    timestamp
    Description

    Tijdstempel van voltooiing, in milliseconden. null als de taak geen voltooiingstijd bevat.

  • Name
    consumed_credits
    Type
    integer
    Description

    Credits verbruikt door deze taak. Retourneert 0 voor FAILED-taken (credits worden bij mislukking terugbetaald).

  • Name
    api_key_name
    Type
    string
    Description

    Weergavenaam van de API-sleutel waarmee de taak is uitgevoerd. Blijft ingevuld voor ingetrokken sleutels, zodat historische uitgaven na sleutelrotatie herleidbaar blijven.

  • Name
    api_key_suffix
    Type
    string
    Description

    Laatste vier tekens van die API-sleutel, om sleutels met dezelfde naam van elkaar te onderscheiden.

Example Usage Record Object

{
  "task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "endpoint": "image-to-3d",
  "status": "SUCCEEDED",
  "created_at": 1755787000000,
  "finished_at": 1755787045000,
  "consumed_credits": 20,
  "api_key_name": "production",
  "api_key_suffix": "a1b2"
}