Usage API

Listet die abgeschlossenen API-Tasks deines Teams und die dabei verbrauchten Credits auf, für Abrechnungsexporte und Kostenberichte.

Um diesen Endpunkt aufzurufen, verwende den API-Schlüssel eines aktiven Mitglieds eines Studio- oder Enterprise-Teams. Jedes Mitglied kann ihn aufrufen, nicht nur Owner und Admins. Mit jedem anderen API-Schlüssel liefert die Anfrage 403.

GET/openapi/v1/usage/tasks

Nutzungsdatensätze auflisten

Liefert eine Seite der Nutzungsdatensätze deines Teams, standardmäßig neueste zuerst. Ohne start_time und end_time umfassen die Datensätze die letzten 30 Tage. Der Aufruf dieses Endpunkts ist kostenlos.

Die Datensätze enthalten folgende Tasks:

API-Tasks, die mit SUCCEEDED oder FAILED abgeschlossen wurden
Tasks jedes aktuellen Teammitglieds, von jedem seiner API-Schlüssel
Von dir gelöschte Tasks und Tasks, deren Dateien abgelaufen sind

Die Datensätze enthalten folgende Tasks nicht:

Tasks, die noch PENDING oder IN_PROGRESS sind, sowie CANCELED-Tasks
Tasks von Personen, die das Team verlassen haben
Creative-Lab-Tasks
Tasks, die von Meshys KI-Agenten ausgeführt wurden
Arbeiten, die in der Meshy-Web-App durchgeführt wurden

Ein Task erscheint erst nach seinem Abschluss in den Datensätzen, im Zeitfenster seines created_at. Meshy belastet Credits bereits bei der Erstellung eines Tasks, daher fehlt ein noch laufender Task in den Datensätzen. Bevor du die Datensätze mit deinem Credit-Guthaben abgleichst, rufe aktuelle Zeitfenster erneut ab oder exportiere nach einer kurzen Verzögerung.

Wenn dein Team eine Datenaufbewahrungsfrist hat, beginnt das Zeitfenster frühestens so weit zurück, wie diese Frist es zulässt.

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

Parameter

Name
page_num
Type
integer
Standard 1
Description
Die zurückzugebende Seite, von 1 bis 255. Ein Wert über 255 liefert 400. Ein Zeitfenster umfasst maximal 255 Seiten, teile einen großen Export also in kürzere Zeitfenster auf.
Name
page_size
Type
integer
Standard 10
Description
Anzahl der Datensätze pro Seite, von 1 bis 100. Ein Wert zwischen 101 und 255 liefert 100 Datensätze, und ein Wert über 255 liefert 400.
Name
sort_by
Type
string
Standard -created_at
Description
Die Sortierreihenfolge.
Verfügbare Werte:
- +created_at: älteste zuerst
- -created_at: neueste zuerst
Schreibe in einer URL + als %2B. Andernfalls wird das + als Leerzeichen gelesen, und die Anfrage liefert 400.
Name
start_time
Type
string
Description
Der Beginn des Zeitfensters, als RFC-3339-Zeitstempel, zum Beispiel 2026-08-01T00:00:00Z. Die Datensätze enthalten Tasks, die zu diesem Zeitpunkt oder danach erstellt wurden. Lass dies weg, damit das Zeitfenster 30 Tage vor end_time beginnt.
Das Zeitfenster kann höchstens 366 Tage umfassen. Ein längeres Zeitfenster liefert 400, teile einen längeren Export also in mehrere Zeitfenster auf.
Name
end_time
Type
string
Description
Das Ende des Zeitfensters, als RFC-3339-Zeitstempel. Die Datensätze enthalten Tasks, die vor diesem Zeitpunkt erstellt wurden. Lass dies weg, um das Zeitfenster zum Zeitpunkt deiner Anfrage enden zu lassen.
Name
endpoints
Type
string
Description
Eine durch Kommas getrennte Liste der einzuschließenden Endpunkte, mit denselben Namen wie das Feld endpoint. Lass dies weg, um alle Endpunkte einzuschließen. Ein unbekannter Name liefert 400.
Verfügbare Werte:
- text-to-3d: jeder Text-zu-3D-Task, preview und refine
- text-to-3d-preview: nur Preview-Tasks
- text-to-3d-refine: nur Refine-Tasks
- 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
Der einzuschließende Status, SUCCEEDED oder FAILED. Lass dies weg, um beide einzuschließen. Jeder andere Wert liefert 400.

Rückgabe

Liefert ein Array von Nutzungsdatensätzen. Das Array ist leer, wenn keine Datensätze übereinstimmen.

Fehlerfälle

Name
400 - Bad Request
Description
Ein Parameter ist ungültig, und die Fehlermeldung gibt an, welcher. Korrigiere den Parameter und sende die Anfrage erneut.
Name
401 - Unauthorized
Description
Der API-Schlüssel fehlt oder ist ungültig. Überprüfe den Authorization-Header.
Name
403 - Forbidden
Description
Das Konto des API-Schlüssels ist kein aktives Mitglied eines Studio- oder Enterprise-Teams. Die Meldung lautet This endpoint is available on Studio and Enterprise plans. Verwende den API-Schlüssel eines Studio- oder Enterprise-Teammitglieds.
Name
429 - Too Many Requests
Description
Du hast zu viele Anfragen gesendet. Warte die in Retry-After angegebene Anzahl Sekunden und versuche es dann erneut.

Das Nutzungsdatensatz-Objekt

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
Die Task-ID, dieselbe ID, die der erstellende Endpunkt zurückgegeben hat. Um den Task selbst mit seinen Ausgabe-URLs abzurufen, sende die ID an die get-Route dieses Endpunkts, zum Beispiel GET /openapi/v1/image-to-3d/{task_id} für einen image-to-3d-Datensatz.
Name
endpoint
Type
string
Description
Der Endpunkt, auf dem der Task ausgeführt wurde, zum Beispiel image-to-3d oder rig. Ein Text-zu-3D-Task zeigt seine Stufe, text-to-3d-preview oder text-to-3d-refine.
Ältere Datensätze können Namen von eingestellten Endpunkten enthalten, die der endpoints-Filter nicht akzeptiert.
Name
status
Type
string
Description
Der endgültige Status des Tasks, SUCCEEDED oder FAILED.
Name
created_at
Type
timestamp
Description
Zeitpunkt, zu dem der Task erstellt wurde, in Unix-Millisekunden.
Name
finished_at
Type
timestamp
Description
Zeitpunkt, zu dem der Task abgeschlossen wurde, in Unix-Millisekunden. null, wenn der Task keinen Abschlusszeitpunkt hat.
Name
consumed_credits
Type
integer
Description
Anzahl der vom Task verbrauchten Credits, nach Rückerstattungen. 0 bei einem fehlgeschlagenen Task, da Meshy diesen erstattet, sowie bei einem kostenlosen Task wie Druckbarkeit analysieren.
Name
api_key_name
Type
string
Description
Der Name des API-Schlüssels, mit dem der Task ausgeführt wurde. Bei einem Task, der über einen App-Login ausgeführt wurde, ist es der Name der App, zum Beispiel Meshy CLI.
In manchen Fällen ist es eine leere Zeichenkette, zum Beispiel:
- Für den Task wurden nie Credits berechnet, etwa bei einem Task vom Typ Druckbarkeit analysieren, der kostenlos ist.
- Der API-Schlüssel wurde gelöscht.
- Der API-Schlüssel wurde erst in den letzten paar Minuten erstellt.
Name
api_key_suffix
Type
string
Description
Die letzten vier Zeichen dieses API-Schlüssels, um Schlüssel mit demselben Namen zu unterscheiden. Eine leere Zeichenkette, wenn api_key_name leer ist, sowie bei App-Logins wie der Meshy CLI.
Name
metadata
Type
object
Description
Die Tags, die im X-Meshy-Metadata-Header bei der Erstellung des Tasks gesendet wurden. {}, wenn keine vorhanden sind. Siehe Metadaten.