Usage API

Usage API returnerar ditt teams historiska API-uppgifter tillsammans med de credits var och en förbrukat. Filtrera efter tidsfönster, endpoint eller status, och bläddra igenom resultaten för att exportera i bulk.

Tillgänglighet. API-nyckeln måste tillhöra ett Studio- eller Enterprise-team; nycklar på någon annan plan, eller utan team, får ett 403-fel.

GET/openapi/v1/usage/tasks

Lista användningsposter

Returnerar en sida av teamets API-uppgifter, nyaste först. Utan ett uttryckligt tidsintervall omfattar svaret de senaste 30 dagarna.

Parametrar

Name
page_num
Type
integer
standard 1
Description
Sidnummer för paginering.
Name
page_size
Type
integer
standard 10
Description
Gräns för sidstorlek. Maximalt tillåtna värde är 100 objekt.
Name
sort_by
Type
string
standard -created_at
Description
Fält att sortera efter.
Tillgängliga värden:
- +created_at: Sortera efter skapandetid i stigande ordning.
- -created_at: Sortera efter skapandetid i fallande ordning.
Name
start_time
Type
string
Description
Start på created_at-fönstret, som en RFC 3339-tidsstämpel (t.ex. 2026-08-01T00:00:00Z). Standard är 30 dagar före end_time. Fönstret kan sträcka sig över högst 1 år — för större exporter, bläddra igenom på varandra följande fönster.
Name
end_time
Type
string
Description
Slut på created_at-fönstret, som en RFC 3339-tidsstämpel. Standard är den aktuella tiden.
Name
endpoints
Type
string
Description
Kommaseparerad lista med endpoint-namn att inkludera. Accepterar samma värden som fältet endpoint i svaret innehåller — 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 — där text-to-3d är ett samlingsbegrepp som täcker både förhandsgranskningsfasen och förfiningsfasen. Utelämna för att inkludera alla endpoints.
Name
status
Type
string
Description
Filtrera efter slutgiltig uppgiftsstatus: SUCCEEDED eller FAILED. Utelämna för att inkludera båda.

Returnerar

Returnerar en paginerad lista med Användningspostobjekt.

Poster omfattar uppgifter som har nått en slutgiltig status. Credits debiteras när en uppgift skapas, så en uppgift som fortfarande körs när du exporterar finns ännu inte med i det fönstrets resultat — hämta om nyliga fönster (eller exportera med en kort fördröjning) om dina totalsummor måste stämma exakt med ditt saldo av credits.

Team med en anpassad datalagringspolicy får poster inom sitt konfigurerade lagringsfönster.

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

Användningspostobjektet

Name
task_id
Type
string
Description
ID för uppgiften som denna post fakturerar — samma ID som den skapande endpointen returnerade. För att hämta själva uppgiften (inklusive dess utdatamodell eller bild-URL:er, om-signerade vid varje läsning), skicka det till motsvarande hämtnings-endpoint, t.ex. GET /openapi/v1/{endpoint}/{task_id}.
Name
endpoint
Type
string
Description
Endpointen som uppgiften kördes på, t.ex. image-to-3d eller text-to-3d-refine. Text till 3D-uppgifter rapporterar sin fas (text-to-3d-preview / text-to-3d-refine).
Name
status
Type
string
Description
Slutgiltig uppgiftsstatus: SUCCEEDED eller FAILED.
Name
created_at
Type
timestamp
Description
Tidsstämpel för när uppgiften skapades, i millisekunder.
Name
finished_at
Type
timestamp
Description
Tidsstämpel för slutförande, i millisekunder. null om uppgiften saknar slutförandetid.
Name
consumed_credits
Type
integer
Description
Credits förbrukade av denna uppgift. Returnerar 0 för FAILED-uppgifter (credits återbetalas vid fel).
Name
api_key_name
Type
string
Description
Visningsnamn för API-nyckeln som körde uppgiften. Förblir ifylld för återkallade nycklar, så att historiska utgifter förblir spårbara efter nyckelrotation.
Name
api_key_suffix
Type
string
Description
De sista fyra tecknen i den API-nyckeln, för att skilja på nycklar med samma namn.

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