Usage API

L'API di utilizzo restituisce lo storico delle attività API del tuo team, con i crediti consumati da ciascuna di esse. Filtra per intervallo di tempo, endpoint o stato, e scorri i risultati pagina per pagina per esportarli in blocco.

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

GET/openapi/v1/usage/tasks

List Usage Records

Restituisce una pagina delle attività API del team, dalla più recente. Senza un intervallo di tempo 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ù ampie, scorri intervalli consecutivi.
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 di 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 è una categoria generale che copre sia la fase preview sia quella refine. Ometti per includere tutti gli endpoint.
Name
status
Type
string
Description
Filtra per stato finale dell'attività: SUCCEEDED o FAILED. Ometti per includere entrambi.

Restituisce

Restituisce un elenco paginato di The Usage Record Objects.

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

I team con una politica di conservazione 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 dell'attività fatturata da questo record — lo stesso ID restituito dall'endpoint che l'ha creata. Per recuperare l'attività stessa (compresi il modello di output o gli URL delle immagini, ri-firmati ad ogni lettura), passalo all'endpoint di recupero corrispondente, ad es. GET /openapi/v1/{endpoint}/{task_id}.
Name
endpoint
Type
string
Description
L'endpoint su cui è stata eseguita l'attività, ad es. image-to-3d o text-to-3d-refine. Le attività di Testo in 3D riportano la propria fase (text-to-3d-preview / text-to-3d-refine).
Name
status
Type
string
Description
Stato finale dell'attività: SUCCEEDED o FAILED.
Name
created_at
Type
timestamp
Description
Timestamp di creazione dell'attività, in millisecondi.
Name
finished_at
Type
timestamp
Description
Timestamp di completamento, in millisecondi. null se l'attività non riporta un orario di completamento.
Name
consumed_credits
Type
integer
Description
Crediti consumati da questa attività. Restituisce 0 per le attività FAILED (i crediti vengono rimborsati in caso di errore).
Name
api_key_name
Type
string
Description
Nome visualizzato della chiave API che ha eseguito l'attività. Resta valorizzato anche per le chiavi revocate, così la spesa storica rimane attribuibile dopo la rotazione delle chiavi.
Name
api_key_suffix
Type
string
Description
Ultimi quattro caratteri di quella chiave API, per distinguere 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"
}