Usage API

Lista ditt teams avslutade API-uppgifter och hur många credits var och en använde, för faktureringsexporter och kostnadsrapporter.

För att anropa denna endpoint, använd en API-nyckel från en aktiv medlem i ett Studio- eller Enterprise-team. Vilken medlem som helst kan anropa den, inte bara ägare och administratörer. Med någon annan API-nyckel returnerar förfrågan 403.

GET/openapi/v1/usage/tasks

Lista användningsposter

Returnerar en sida av ditt teams användningsposter, som standard nyast först. Utan start_time och end_time täcker posterna de senaste 30 dagarna. Det är gratis att anropa denna endpoint.

Posterna inkluderar dessa uppgifter:

API-uppgifter som avslutades med SUCCEEDED eller FAILED
Uppgifter från varje nuvarande medlem i teamet, från någon av deras API-nycklar
Uppgifter du har tagit bort, och uppgifter vars filer har löpt ut

Posterna utelämnar dessa uppgifter:

Uppgifter som fortfarande är PENDING eller IN_PROGRESS, samt CANCELED-uppgifter
Uppgifter från personer som har lämnat teamet
Creative Lab-uppgifter
Uppgifter som Meshys AI-agenter har kört
Arbete som utförts i Meshys webbapp

En uppgift visas i posterna först efter att den är klar, inom fönstret för dess created_at. Meshy drar credits när den skapar en uppgift, så en uppgift som fortfarande körs saknas i posterna. Innan du stämmer av posterna mot ditt credit-saldo, hämta de senaste fönstren igen, eller exportera efter en kort fördröjning.

Om ditt team har en period för datalagring börjar fönstret aldrig tidigare än vad den perioden tillåter.

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

Parametrar

Name
page_num
Type
integer
standard 1
Description
Sidan som ska returneras, från 1 till 255. Ett värde över 255 returnerar 400. Ett fönster rymmer högst 255 sidor, så dela upp en stor export i kortare fönster.
Name
page_size
Type
integer
standard 10
Description
Antal poster per sida, från 1 till 100. Ett värde från 101 till 255 returnerar 100 poster, och ett värde över 255 returnerar 400.
Name
sort_by
Type
string
standard -created_at
Description
Sorteringsordningen.
Tillgängliga värden:
- +created_at: äldst först
- -created_at: nyast först
I en URL, skriv + som %2B. Annars tolkas + som ett mellanslag, och förfrågan returnerar 400.
Name
start_time
Type
string
Description
Starten av fönstret, som en RFC 3339-tidsstämpel, till exempel 2026-08-01T00:00:00Z. Posterna inkluderar uppgifter skapade vid eller efter denna tidpunkt. Utelämna den för att starta fönstret 30 dagar före end_time.
Fönstret kan omfatta som mest 366 dagar. Ett längre fönster returnerar 400, så dela upp en längre export i flera fönster.
Name
end_time
Type
string
Description
Slutet av fönstret, som en RFC 3339-tidsstämpel. Posterna inkluderar uppgifter skapade före denna tidpunkt. Utelämna den för att avsluta fönstret vid tidpunkten för din förfrågan.
Name
endpoints
Type
string
Description
En kommaseparerad lista över de endpoints som ska inkluderas, med samma namn som fältet endpoint. Utelämna den för att inkludera varje endpoint. Ett okänt namn returnerar 400.
Tillgängliga värden:
- text-to-3d: alla Text till 3D-uppgifter, preview och refine
- text-to-3d-preview: endast preview-uppgifter
- text-to-3d-refine: endast refine-uppgifter
- 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
Statusen som ska inkluderas, SUCCEEDED eller FAILED. Utelämna den för att inkludera båda. Alla andra värden returnerar 400.

Returnerar

Returnerar en array med användningsposter. Arrayen är tom när inga poster matchar.

Felscenarier

Name
400 - Bad Request
Description
En parameter är ogiltig, och felmeddelandet anger vilken. Åtgärda parametern och skicka förfrågan igen.
Name
401 - Unauthorized
Description
API-nyckeln saknas eller är ogiltig. Kontrollera Authorization-headern.
Name
403 - Forbidden
Description
API-nyckelns konto är inte en aktiv medlem i ett Studio- eller Enterprise-team. Meddelandet är This endpoint is available on Studio and Enterprise plans. Använd en API-nyckel från en medlem i ett Studio- eller Enterprise-team.
Name
429 - Too Many Requests
Description
Du har skickat för många förfrågningar. Vänta det antal sekunder som anges i Retry-After, och försök sedan igen.

Objektet för användningspost

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
Uppgifts-ID:t, samma ID som den skapande endpointen returnerade. För att hämta själva uppgiften, med dess utdata-URL:er, skicka ID:t till den endpointens get-route, till exempel GET /openapi/v1/image-to-3d/{task_id} för en image-to-3d-post.
Name
endpoint
Type
string
Description
Endpointen som uppgiften kördes på, till exempel image-to-3d eller rig. En Text till 3D-uppgift visar sitt stadium, text-to-3d-preview eller text-to-3d-refine.
Äldre poster kan ha namn på nedlagda endpoints, vilka filtret endpoints inte accepterar.
Name
status
Type
string
Description
Uppgiftens slutliga status, SUCCEEDED eller FAILED.
Name
created_at
Type
timestamp
Description
Tidpunkt då uppgiften skapades, i Unix-millisekunder.
Name
finished_at
Type
timestamp
Description
Tidpunkt då uppgiften avslutades, i Unix-millisekunder. null om uppgiften saknar sluttid.
Name
consumed_credits
Type
integer
Description
Antal credits uppgiften använde, efter återbetalningar. 0 för en misslyckad uppgift, eftersom Meshy återbetalar den, och för en gratis uppgift som Analysera utskrivbarhet.
Name
api_key_name
Type
string
Description
Namnet på API-nyckeln som körde uppgiften. För en uppgift som körts med en appinloggning är det appens namn, till exempel Meshy CLI.
Det är en tom sträng i vissa fall, till exempel:
- Uppgiften debiterades aldrig, till exempel en Analysera utskrivbarhet-uppgift, som är gratis.
- API-nyckeln har tagits bort.
- API-nyckeln skapades för några minuter sedan.
Name
api_key_suffix
Type
string
Description
De sista fyra tecknen i den API-nyckeln, för att skilja nycklar med samma namn åt. En tom sträng när api_key_name är tom, och för appinloggningar som Meshy CLI.
Name
metadata
Type
object
Description
Taggarna som skickades i headern X-Meshy-Metadata när uppgiften skapades. {} om inga finns. Se Metadata.