Usage API

L'API Usage restituisce i task API storici del tuo team con i crediti consumati da ciascuno. Filtra per intervallo temporale, endpoint o stato e scorri i risultati per esportarli in blocco.

Disponibilità. La chiave API deve appartenere a un team Studio o Enterprise; le chiavi di qualsiasi altro piano, o senza un team, ricevono un 403.

GET/openapi/v1/usage/tasks

List Usage Records

Restituisce una pagina dei task API del team, dal più recente. Senza un intervallo temporale esplicito, la risposta copre gli ultimi 30 giorni.

Parametri

Name
page_num
Type
integer
predefinito 1
Description
Numero di pagina per la paginazione.
Name
page_size
Type
integer
predefinito 10
Description
Limite di dimensione della pagina. Il massimo consentito è 100 elementi.
Name
sort_by
Type
string
predefinito -created_at
Description
Campo per l'ordinamento.
Valori disponibili:
- +created_at: Ordina per data di creazione in ordine crescente.
- -created_at: Ordina per data di creazione in ordine decrescente.
Name
start_time
Type
string
Description
Inizio dell'intervallo created_at, come timestamp RFC 3339 (es. 2026-08-01T00:00:00Z). Il valore predefinito è 30 giorni prima di end_time. L'intervallo può coprire al massimo 1 anno — per esportazioni più grandi, scorri finestre consecutive.
Name
end_time
Type
string
Description
Fine dell'intervallo created_at, come timestamp RFC 3339. Il valore predefinito è l'ora corrente.
Name
endpoints
Type
string
Description
Elenco separato da virgole dei nomi degli endpoint da includere. Accetta gli stessi valori riportati dal campo di risposta endpoint — 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 — dove text-to-3d è un termine generico che copre sia la fase preview sia quella refine. Omettilo per includere tutti gli endpoint.
Name
status
Type
string
Description
Filtra per stato finale del task: SUCCEEDED o FAILED. Omettilo per includerli entrambi.

Restituisce

Restituisce un elenco paginato di The Usage Record Objects.

I record coprono i task che hanno raggiunto uno stato finale. I crediti vengono addebitati alla creazione di un task, quindi un task ancora in esecuzione al momento dell'esportazione non compare ancora nei risultati di quella finestra — riesegui l'estrazione delle finestre recenti (o esporta con un breve ritardo) se i totali devono corrispondere esattamente al tuo saldo crediti.

I team con una policy di conservazione dei dati personalizzata ricevono i record entro la finestra di conservazione configurata.

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 del task fatturato da questo record — lo stesso ID restituito dall'endpoint di creazione. Per recuperare il task stesso (incluso il modello di output o gli URL delle immagini, ri-firmati a ogni lettura), passalo al corrispondente endpoint di recupero, es. GET /openapi/v1/{endpoint}/{task_id}.
Name
endpoint
Type
string
Description
L'endpoint su cui è stato eseguito il task, es. image-to-3d o text-to-3d-refine. I task di Testo in 3D riportano la propria fase (text-to-3d-preview / text-to-3d-refine).
Name
status
Type
string
Description
Stato finale del task: SUCCEEDED o FAILED.
Name
created_at
Type
timestamp
Description
Timestamp di creazione del task, in millisecondi.
Name
finished_at
Type
timestamp
Description
Timestamp di completamento, in millisecondi. null se il task non riporta un orario di completamento.
Name
consumed_credits
Type
integer
Description
Crediti consumati da questo task. Restituisce 0 per i task FAILED (i crediti vengono rimborsati in caso di errore).
Name
api_key_name
Type
string
Description
Nome visualizzato della chiave API che ha eseguito il task. Rimane popolato anche per le chiavi revocate, così la spesa storica resta attribuibile dopo la rotazione delle chiavi.
Name
api_key_suffix
Type
string
Description
Ultimi quattro caratteri di quella chiave API, per distinguere tra chiavi con lo stesso nome.

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"
}