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 tijdvenster, endpoint of status, en blader door de resultaten om ze in bulk te exporteren.

Beschikbaarheid. De API-sleutel moet bij een Studio- of Enterprise-team horen; sleutels op elk ander plan, of zonder team, krijgen een 403.

GET/openapi/v1/usage/tasks

Gebruiksrecords weergeven

Geeft één pagina met de 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 voor end_time. Het venster kan maximaal 1 jaar omvatten — voor grotere exports, blader 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-antwoordveld draagt — 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, print-split — 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 definitieve taakstatus: SUCCEEDED of FAILED. Laat weg om beide op te nemen.

Retourneert

Geeft een gepagineerde lijst van Het gebruiksrecordobject terug.

Records omvatten taken die een definitieve status 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 beleid voor gegevensbewaring 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"
  }
]

Het gebruiksrecordobject

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 de uitvoermodel- of afbeelding-URL's, opnieuw ondertekend bij elke lezing), geef je deze door aan de bijbehorende ophaal-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
Definitieve taakstatus: SUCCEEDED of FAILED.
Name
created_at
Type
timestamp
Description
Tijdstempel van taakaanmaak, 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 terugbetaald bij falen).
Name
api_key_name
Type
string
Description
Weergavenaam van de API-sleutel die de taak heeft 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"
}