Usage API

Die Usage API gibt die historischen API-Tasks deines Teams zusammen mit den dabei jeweils verbrauchten Credits zurück. Filtere nach Zeitfenster, Endpunkt oder Status und blättere durch die Ergebnisse, um sie in großen Mengen zu exportieren.

Verfügbarkeit. Der API-Schlüssel muss zu einem Studio- oder Enterprise-Team gehören; Schlüssel in jedem anderen Plan oder ohne Team erhalten einen 403.

GET/openapi/v1/usage/tasks

Nutzungsdatensätze auflisten

Gibt eine Seite der API-Tasks des Teams zurück, neueste zuerst. Ohne explizit angegebenen Zeitraum umfasst die Antwort die letzten 30 Tage.

Parameter

Name
page_num
Type
integer
Standard 1
Description
Seitenzahl für die Paginierung.
Name
page_size
Type
integer
Standard 10
Description
Limit für die Seitengröße. Maximal zulässig sind 100 Einträge.
Name
sort_by
Type
string
Standard -created_at
Description
Feld, nach dem sortiert werden soll.
Verfügbare Werte:
- +created_at: Sortierung nach Erstellungszeitpunkt aufsteigend.
- -created_at: Sortierung nach Erstellungszeitpunkt absteigend.
Name
start_time
Type
string
Description
Beginn des created_at-Fensters, als RFC-3339-Zeitstempel (z. B. 2026-08-01T00:00:00Z). Standardmäßig 30 Tage vor end_time. Das Fenster darf höchstens 1 Jahr umfassen — für größere Exporte durch aufeinanderfolgende Fenster blättern.
Name
end_time
Type
string
Description
Ende des created_at-Fensters, als RFC-3339-Zeitstempel. Standardmäßig der aktuelle Zeitpunkt.
Name
endpoints
Type
string
Description
Durch Kommas getrennte Liste der einzuschließenden Endpunktnamen. Akzeptiert dieselben Werte, die das Antwortfeld endpoint trägt — 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, print-split — wobei text-to-3d beide Phasen, preview und refine, als Oberbegriff abdeckt. Weglassen, um alle Endpunkte einzuschließen.
Name
status
Type
string
Description
Filtert nach dem finalen Task-Status: SUCCEEDED oder FAILED. Weglassen, um beide einzuschließen.

Rückgabewerte

Gibt eine paginierte Liste von Nutzungsdatensatz-Objekten zurück.

Die Datensätze umfassen Tasks, die einen finalen Status erreicht haben. Credits werden bei der Erstellung eines Tasks abgebucht, daher ist ein Task, der beim Export noch läuft, noch nicht in den Ergebnissen dieses Fensters enthalten — rufe aktuelle Fenster erneut ab (oder exportiere mit kurzer Verzögerung), wenn deine Summen exakt mit deinem Credit-Guthaben übereinstimmen müssen.

Teams mit einer benutzerdefinierten Datenaufbewahrungsrichtlinie erhalten Datensätze innerhalb ihres konfigurierten Aufbewahrungsfensters.

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

Das Nutzungsdatensatz-Objekt

Name
task_id
Type
string
Description
ID des Tasks, der mit diesem Datensatz abgerechnet wird — dieselbe ID, die der erstellende Endpunkt zurückgegeben hat. Um den Task selbst abzurufen (einschließlich der Modell- oder Bild-URLs seiner Ausgabe, die bei jedem Lesevorgang neu signiert werden), übergib sie an den entsprechenden Abruf-Endpunkt, z. B. GET /openapi/v1/{endpoint}/{task_id}.
Name
endpoint
Type
string
Description
Der Endpunkt, auf dem der Task ausgeführt wurde, z. B. image-to-3d oder text-to-3d-refine. Text-zu-3D-Tasks melden ihre Phase (text-to-3d-preview / text-to-3d-refine).
Name
status
Type
string
Description
Finaler Task-Status: SUCCEEDED oder FAILED.
Name
created_at
Type
timestamp
Description
Zeitstempel der Task-Erstellung, in Millisekunden.
Name
finished_at
Type
timestamp
Description
Zeitstempel des Abschlusses, in Millisekunden. null, wenn der Task keinen Abschlusszeitpunkt trägt.
Name
consumed_credits
Type
integer
Description
Von diesem Task verbrauchte Credits. Gibt 0 für FAILED-Tasks zurück (Credits werden bei einem Fehlschlag zurückerstattet).
Name
api_key_name
Type
string
Description
Anzeigename des API-Schlüssels, mit dem der Task ausgeführt wurde. Bleibt auch für widerrufene Schlüssel erhalten, sodass historische Ausgaben nach einer Schlüsselrotation weiterhin zuordenbar bleiben.
Name
api_key_suffix
Type
string
Description
Die letzten vier Zeichen dieses API-Schlüssels, um Schlüssel mit demselben Namen unterscheiden zu können.

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