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