Usage API

Die Usage API gibt die historischen API-Tasks Ihres Teams zusammen mit den dabei verbrauchten Credits zurück. Filtern Sie nach Zeitfenster, Endpunkt oder Status und blättern Sie durch die Ergebnisse, um sie in großem Umfang 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

List Usage Records

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

Parameter

  • Name
    page_num
    Type
    integer
    Standard 1
    Description

    Seitennummer für die Paginierung.

  • Name
    page_size
    Type
    integer
    Standard 10
    Description

    Begrenzung der 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 Erstellungszeit in aufsteigender Reihenfolge.
    • -created_at: Sortierung nach Erstellungszeit in absteigender Reihenfolge.
  • Name
    start_time
    Type
    string
    Description

    Anfang 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 maximal 1 Jahr umfassen — für größere Exporte blättern Sie durch aufeinanderfolgende Fenster.

  • Name
    end_time
    Type
    string
    Description

    Ende des created_at-Fensters, als RFC-3339-Zeitstempel. Standardmäßig die aktuelle Zeit.

  • Name
    endpoints
    Type
    string
    Description

    Kommagetrennte 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 — wobei text-to-3d als Oberbegriff sowohl die Preview- als auch die Refine-Phase abdeckt. Weglassen, um alle Endpunkte einzuschließen.

  • Name
    status
    Type
    string
    Description

    Filtern nach abschließendem Task-Status: SUCCEEDED oder FAILED. Weglassen, um beide einzuschließen.

Rückgabewerte

Gibt eine paginierte Liste von The Usage Record Objects zurück.

Einträge decken Tasks ab, die einen abschließenden Status erreicht haben. Credits werden bei der Erstellung eines Tasks belastet, sodass ein Task, der beim Export noch läuft, noch nicht in den Ergebnissen dieses Fensters enthalten ist — rufen Sie aktuelle Fenster erneut ab (oder exportieren Sie mit kurzer Verzögerung), wenn Ihre Summen exakt mit Ihrem Guthaben übereinstimmen müssen.

Teams mit einer benutzerdefinierten Datenaufbewahrungsrichtlinie erhalten Einträge 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"
  }
]

The Usage Record Object

  • Name
    task_id
    Type
    string
    Description

    ID des Tasks, den dieser Eintrag abrechnet — dieselbe ID, die der erstellende Endpunkt zurückgegeben hat. Um den Task selbst abzurufen (einschließlich der Ausgabe-Modell- oder Bild-URLs, die bei jedem Lesevorgang neu signiert werden), übergeben Sie sie an den entsprechenden Retrieve-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

    Abschließender 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 keine Abschlusszeit trägt.

  • Name
    consumed_credits
    Type
    integer
    Description

    Von diesem Task verbrauchte Credits. Gibt 0 für FAILED-Tasks zurück (Credits werden bei Fehlschlag erstattet).

  • Name
    api_key_name
    Type
    string
    Description

    Anzeigename des API-Schlüssels, mit dem der Task ausgeführt wurde. Bleibt 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 voneinander 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"
}