Usage API

Bekijk de afgeronde API-taken van je team en het aantal credits dat elke taak heeft gebruikt, voor facturatie-exports en kostenrapporten.

Gebruik voor deze endpoint een API-sleutel van een actief lid van een Studio- of Enterprise-team. Elk lid kan deze aanroepen, niet alleen eigenaren en beheerders. Met elke andere API-sleutel geeft het verzoek 403 terug.

GET/openapi/v1/usage/tasks

Gebruiksrecords weergeven

Geeft één pagina met gebruiksrecords van je team terug, standaard nieuwste eerst. Zonder start_time en end_time bestrijken de records de laatste 30 dagen. Het aanroepen van deze endpoint is gratis.

De records bevatten deze taken:

API-taken die zijn afgerond als SUCCEEDED of FAILED
Taken van elk huidig teamlid, vanaf elk van hun API-sleutels
Taken die je hebt verwijderd, en taken waarvan de bestanden zijn verlopen

De records bevatten deze taken niet:

Taken die nog PENDING of IN_PROGRESS zijn, en CANCELED-taken
Taken van personen die het team hebben verlaten
Creative Lab-taken
Taken die door Meshy's AI-agents zijn uitgevoerd
Werk dat is gedaan in de Meshy web-app

Een taak verschijnt pas in de records nadat deze is afgerond, binnen het venster van de created_at. Meshy brengt credits in rekening op het moment dat het een taak aanmaakt, dus een taak die nog loopt ontbreekt in de records. Voordat je de records afstemt op je creditsaldo, haal je recente vensters opnieuw op, of exporteer je na een korte vertraging.

Als je team een bewaartermijn voor gegevens heeft, begint het venster niet eerder dan die termijn toestaat.

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",
    "metadata": {
      "user": "alex@example.com",
      "team": "fab"
    }
  },
  {
    "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",
    "metadata": {}
  }
]

Parameters

Name
page_num
Type
integer
standaard 1
Description
De pagina die wordt teruggegeven, van 1 tot 255. Een waarde boven 255 geeft 400 terug. Eén venster bevat maximaal 255 pagina's, dus splits een grote export op in kortere vensters.
Name
page_size
Type
integer
standaard 10
Description
Aantal records per pagina, van 1 tot 100. Een waarde van 101 tot 255 geeft 100 records terug, en een waarde boven 255 geeft 400 terug.
Name
sort_by
Type
string
standaard -created_at
Description
De sorteervolgorde.
Beschikbare waarden:
- +created_at: oudste eerst
- -created_at: nieuwste eerst
Schrijf in een URL + als %2B. Anders wordt de + gelezen als een spatie, en geeft het verzoek 400 terug.
Name
start_time
Type
string
Description
Het begin van het venster, als een RFC 3339-tijdstempel, bijvoorbeeld 2026-08-01T00:00:00Z. De records bevatten taken die zijn aangemaakt op of na dit tijdstip. Laat dit weg om het venster 30 dagen vóór end_time te laten beginnen.
Het venster kan maximaal 366 dagen beslaan. Een langer venster geeft 400 terug, dus splits een langere export op in meerdere vensters.
Name
end_time
Type
string
Description
Het einde van het venster, als een RFC 3339-tijdstempel. De records bevatten taken die vóór dit tijdstip zijn aangemaakt. Laat dit weg om het venster te laten eindigen op het moment van je verzoek.
Name
endpoints
Type
string
Description
Een door komma's gescheiden lijst van de endpoints die moeten worden opgenomen, met dezelfde namen als het veld endpoint. Laat dit weg om elke endpoint op te nemen. Een onbekende naam geeft 400 terug.
Beschikbare waarden:
- text-to-3d: elke Tekst naar 3D-taak, preview en refine
- text-to-3d-preview: alleen preview-taken
- text-to-3d-refine: alleen refine-taken
- 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
Name
status
Type
string
Description
De status die moet worden opgenomen, SUCCEEDED of FAILED. Laat dit weg om beide op te nemen. Elke andere waarde geeft 400 terug.

Retourwaarden

Geeft een array van gebruiksrecords terug. De array is leeg wanneer er geen records overeenkomen.

Foutmodi

Name
400 - Bad Request
Description
Een parameter is ongeldig, en het foutbericht vermeldt welke. Corrigeer de parameter en stuur het verzoek opnieuw.
Name
401 - Unauthorized
Description
De API-sleutel ontbreekt of is ongeldig. Controleer de Authorization-header.
Name
403 - Forbidden
Description
Het account van de API-sleutel is geen actief lid van een Studio- of Enterprise-team. Het bericht is This endpoint is available on Studio and Enterprise plans. Gebruik een API-sleutel van een lid van een Studio- of Enterprise-team.
Name
429 - Too Many Requests
Description
Je hebt te veel verzoeken verstuurd. Wacht het aantal seconden dat in Retry-After staat, en probeer het dan opnieuw.

Het gebruiksrecord-object

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",
  "metadata": {
    "user": "alex@example.com",
    "team": "fab"
  }
}

Name
task_id
Type
string
Description
De taak-ID, dezelfde ID die de aanmakende endpoint teruggaf. Om de taak zelf op te halen, met de output-URL's, stuur je de ID naar de get-route van die endpoint, bijvoorbeeld GET /openapi/v1/image-to-3d/{task_id} voor een image-to-3d-record.
Name
endpoint
Type
string
Description
De endpoint waarop de taak is uitgevoerd, bijvoorbeeld image-to-3d of rig. Een Tekst naar 3D-taak toont zijn fase, text-to-3d-preview of text-to-3d-refine.
Oudere records kunnen namen van uitgefaseerde endpoints bevatten, die het filter endpoints niet accepteert.
Name
status
Type
string
Description
De uiteindelijke status van de taak, SUCCEEDED of FAILED.
Name
created_at
Type
timestamp
Description
Tijdstip waarop de taak is aangemaakt, in Unix-milliseconden.
Name
finished_at
Type
timestamp
Description
Tijdstip waarop de taak is afgerond, in Unix-milliseconden. null als de taak geen eindtijd heeft.
Name
consumed_credits
Type
integer
Description
Aantal credits dat de taak heeft gebruikt, na terugbetalingen. 0 voor een mislukte taak, omdat Meshy deze terugbetaalt, en voor een gratis taak zoals Printbaarheid analyseren.
Name
api_key_name
Type
string
Description
De naam van de API-sleutel waarmee de taak is uitgevoerd. Voor een taak die is uitgevoerd met een app-login, is dit de naam van de app, bijvoorbeeld Meshy CLI.
Het is in sommige gevallen een lege string, bijvoorbeeld:
- Er zijn nooit kosten in rekening gebracht voor de taak, zoals een Printbaarheid analyseren-taak, die gratis is.
- De API-sleutel is verwijderd.
- De API-sleutel is in de afgelopen paar minuten aangemaakt.
Name
api_key_suffix
Type
string
Description
De laatste vier tekens van die API-sleutel, om sleutels met dezelfde naam van elkaar te onderscheiden. Een lege string wanneer api_key_name leeg is, en voor app-logins zoals de Meshy CLI.
Name
metadata
Type
object
Description
De tags die zijn verstuurd in de header X-Meshy-Metadata toen de taak werd aangemaakt. {} indien geen. Zie Metadata.