Usage API

Elenca le attività API completate dal tuo team e i crediti usati da ciascuna, per esportazioni di fatturazione e report sui costi.

Per chiamare questo endpoint, usa una chiave API di un membro attivo di un team Studio o Enterprise. Qualsiasi membro può chiamarlo, non solo i proprietari e gli amministratori. Con qualsiasi altra chiave API, la richiesta restituisce 403.

GET/openapi/v1/usage/tasks

Elenca i record di utilizzo

Restituisce una pagina dei record di utilizzo del tuo team, per impostazione predefinita dal più recente al meno recente. Senza start_time ed end_time, i record coprono gli ultimi 30 giorni. Chiamare questo endpoint è gratuito.

I record includono queste attività:

Attività API terminate come SUCCEEDED o FAILED
Attività di ogni membro attuale del team, da qualsiasi loro chiave API
Attività che hai eliminato e attività i cui file sono scaduti

I record escludono queste attività:

Attività ancora PENDING o IN_PROGRESS, e attività CANCELED
Attività di persone che hanno lasciato il team
Attività di Creative Lab
Attività eseguite dagli agenti AI di Meshy
Lavoro svolto nell'app web di Meshy

Un'attività compare nei record solo dopo essere terminata, nella finestra del suo created_at. Meshy addebita i crediti quando crea un'attività, quindi un'attività ancora in esecuzione è assente dai record. Prima di riconciliare i record con il tuo saldo crediti, recupera di nuovo le finestre recenti, oppure esporta dopo un breve ritardo.

Se il tuo team ha un periodo di conservazione dei dati, la finestra non inizia prima di quanto consentito da tale periodo.

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": {}
  }
]

Parametri

Name
page_num
Type
integer
predefinito 1
Description
La pagina da restituire, da 1 a 255. Un valore superiore a 255 restituisce 400. Una finestra contiene al massimo 255 pagine, quindi suddividi un'esportazione di grandi dimensioni in finestre più brevi.
Name
page_size
Type
integer
predefinito 10
Description
Numero di record per pagina, da 1 a 100. Un valore da 101 a 255 restituisce 100 record, e un valore superiore a 255 restituisce 400.
Name
sort_by
Type
string
predefinito -created_at
Description
L'ordine di ordinamento.
Valori disponibili:
- +created_at: dal meno recente
- -created_at: dal più recente
In un URL, scrivi + come %2B. Altrimenti il + viene letto come uno spazio, e la richiesta restituisce 400.
Name
start_time
Type
string
Description
L'inizio della finestra, come timestamp RFC 3339, ad esempio 2026-08-01T00:00:00Z. I record includono le attività create in corrispondenza o dopo questo orario. Ometti per iniziare la finestra 30 giorni prima di end_time.
La finestra può coprire al massimo 366 giorni. Una finestra più lunga restituisce 400, quindi suddividi un'esportazione più lunga in più finestre.
Name
end_time
Type
string
Description
La fine della finestra, come timestamp RFC 3339. I record includono le attività create prima di questo orario. Ometti per terminare la finestra all'orario della tua richiesta.
Name
endpoints
Type
string
Description
Un elenco separato da virgole degli endpoint da includere, con gli stessi nomi del campo endpoint. Ometti per includere ogni endpoint. Un nome sconosciuto restituisce 400.
Valori disponibili:
- text-to-3d: ogni attività Testo in 3D, preview e refine
- text-to-3d-preview: solo attività preview
- text-to-3d-refine: solo attività 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
Name
status
Type
string
Description
Lo stato da includere, SUCCEEDED o FAILED. Ometti per includere entrambi. Qualsiasi altro valore restituisce 400.

Restituisce

Restituisce un array di record di utilizzo. L'array è vuoto quando nessun record corrisponde.

Modalità di errore

Name
400 - Bad Request
Description
Un parametro non è valido, e il messaggio di errore indica quale. Correggi il parametro, quindi invia nuovamente la richiesta.
Name
401 - Unauthorized
Description
La chiave API è mancante o non valida. Controlla l'header Authorization.
Name
403 - Forbidden
Description
L'account della chiave API non è un membro attivo di un team Studio o Enterprise. Il messaggio è This endpoint is available on Studio and Enterprise plans. Usa una chiave API di un membro di un team Studio o Enterprise.
Name
429 - Too Many Requests
Description
Hai inviato troppe richieste. Attendi il numero di secondi indicato in Retry-After, quindi riprova.

Oggetto record di utilizzo

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
L'ID dell'attività, lo stesso ID restituito dall'endpoint che l'ha creata. Per ottenere l'attività stessa, con i suoi URL di output, invia l'ID alla rotta get di quell'endpoint, ad esempio GET /openapi/v1/image-to-3d/{task_id} per un record image-to-3d.
Name
endpoint
Type
string
Description
L'endpoint su cui è stata eseguita l'attività, ad esempio image-to-3d o rig. Un'attività Testo in 3D mostra la sua fase, text-to-3d-preview o text-to-3d-refine.
I record più vecchi possono avere nomi di endpoint ritirati, che il filtro endpoints non accetta.
Name
status
Type
string
Description
Lo stato finale dell'attività, SUCCEEDED o FAILED.
Name
created_at
Type
timestamp
Description
Orario di creazione dell'attività, in millisecondi Unix.
Name
finished_at
Type
timestamp
Description
Orario di conclusione dell'attività, in millisecondi Unix. null se l'attività non ha un orario di conclusione.
Name
consumed_credits
Type
integer
Description
Numero di crediti usati dall'attività, dopo i rimborsi. 0 per un'attività fallita, perché Meshy la rimborsa, e per un'attività gratuita come Analizza stampabilità.
Name
api_key_name
Type
string
Description
Il nome della chiave API che ha eseguito l'attività. Per un'attività eseguita con un login da app, è il nome dell'app, ad esempio Meshy CLI.
È una stringa vuota in alcuni casi, ad esempio:
- L'attività non è mai stata addebitata, come un'attività Analizza stampabilità, che è gratuita.
- La chiave API è stata eliminata.
- La chiave API è stata creata negli ultimi minuti.
Name
api_key_suffix
Type
string
Description
Gli ultimi quattro caratteri di quella chiave API, per distinguere chiavi con lo stesso nome. Una stringa vuota ogni volta che api_key_name è vuoto, e per i login da app come Meshy CLI.
Name
metadata
Type
object
Description
I tag inviati nell'header X-Meshy-Metadata quando l'attività è stata creata. {} se nessuno. Vedi Metadata.