Usage API

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

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

GET/openapi/v1/usage/tasks

List Usage Records

Geeft één pagina met API-taken van het team terug, nieuwste eerst. Zonder expliciet tijdsbereik omvat het antwoord 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 mag maximaal 1 jaar beslaan — gebruik voor grotere exports opeenvolgende vensters met paginering.
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
Komma-gescheiden lijst van endpoint-namen om op te nemen. Accepteert dezelfde waarden die het endpoint-veld in het antwoord 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. Laat weg om elke endpoint op te nemen.
Name
status
Type
string
Description
Filter op eindstatus van de taak: SUCCEEDED of FAILED. Laat weg om beide op te nemen.

Returns

Geeft een gepagineerde lijst van The Usage Record Objects terug.

Records omvatten taken die een eindstatus hebben bereikt. Credits worden in rekening gebracht op het moment dat een taak wordt aangemaakt, dus een taak die nog draait op het moment van exporteren, zit 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 gegevensbewaarbeleid ontvangen records binnen hun geconfigureerde bewaarvenster.

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 de aanmakende endpoint teruggaf. Om de taak zelf op te halen (inclusief het uitvoermodel of de afbeelding-URL's, die bij elke leesactie opnieuw worden ondertekend), geef je deze door aan de bijbehorende retrieve-endpoint, bijv. GET /openapi/v1/{endpoint}/{task_id}.
Name
endpoint
Type
string
Description
De 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. Geeft 0 terug 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 traceerbaar blijven na het roteren van sleutels.
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"
}