Usage API
Usage APIは、チームの過去のAPIタスクと、それぞれが消費したクレジットを返します。時間範囲、エンドポイント、またはステータスでフィルタリングし、結果をページ送りして一括エクスポートできます。
利用可否について。 APIキーはStudioまたはEnterpriseチームに属している必要があります。それ以外のプランのキー、またはチームに属していないキーは403を受け取ります。
List Usage Records
チームのAPIタスクを新しい順に1ページ分返します。明示的な時間範囲を指定しない場合、レスポンスは過去30日間をカバーします。
パラメータ
- Name
- page_num
- Type
- integer
- デフォルト 1
- Description
ページネーション用のページ番号。
- Name
- page_size
- Type
- integer
- デフォルト 10
- Description
ページサイズの上限。最大
100件まで指定可能です。
- Name
- sort_by
- Type
- string
- デフォルト -created_at
- Description
並べ替えに使用するフィールド。
利用可能な値:
+created_at: 作成日時の昇順で並べ替えます。-created_at: 作成日時の降順で並べ替えます。
- Name
- start_time
- Type
- string
- Description
created_atウィンドウの開始点で、RFC 3339形式のタイムスタンプ（例:2026-08-01T00:00:00Z）で指定します。デフォルトはend_timeの30日前です。ウィンドウは最大1年まで指定できます。それより大きなエクスポートが必要な場合は、連続するウィンドウをページ送りしてください。
- Name
- end_time
- Type
- string
- Description
created_atウィンドウの終了点で、RFC 3339形式のタイムスタンプで指定します。デフォルトは現在時刻です。
- Name
- endpoints
- Type
- string
- Description
対象に含めるエンドポイント名のカンマ区切りリスト。
endpointレスポンスフィールドが持つのと同じ値を受け付けます —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。ここでtext-to-3dはプレビューとrefineの両フェーズを包括する総称です。省略した場合、すべてのエンドポイントが対象になります。
- Name
- status
- Type
- string
- Description
終了ステータスでフィルタリングします:
SUCCEEDEDまたはFAILED。省略した場合、両方が対象になります。
戻り値
The Usage Record Objectsのページネーションされたリストを返します。
レコードは終了ステータスに達したタスクを対象とします。クレジットはタスク作成時に課金されるため、エクスポート時にまだ実行中のタスクはそのウィンドウの結果にはまだ含まれません。合計値をクレジット残高と正確に一致させる必要がある場合は、直近のウィンドウを再取得するか（または短い遅延を挟んでエクスポートするか）してください。
カスタムのデータ保持ポリシーを持つチームは、設定された保持期間内のレコードを受け取ります。
Request
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 — タスクを作成したエンドポイントが返したものと同じIDです。タスク自体（読み取りのたびに再署名される出力モデルや画像のURLを含む）を取得するには、対応する取得用エンドポイント、例えば
GET /openapi/v1/{endpoint}/{task_id}にこのIDを渡してください。
- Name
- endpoint
- Type
- string
- Description
タスクが実行されたエンドポイント。例:
image-to-3dやtext-to-3d-refine。テキストから3Dタスクは、そのフェーズ（text-to-3d-preview/text-to-3d-refine）を報告します。
- Name
- status
- Type
- string
- Description
終了ステータス:
SUCCEEDEDまたはFAILED。
- Name
- created_at
- Type
- timestamp
- Description
タスク作成時のタイムスタンプ（ミリ秒単位）。
- Name
- finished_at
- Type
- timestamp
- Description
完了時のタイムスタンプ（ミリ秒単位）。タスクに完了時刻がない場合は
nullです。
- Name
- consumed_credits
- Type
- integer
- Description
このタスクで消費されたクレジット数。
FAILEDのタスクでは0が返されます（失敗時にはクレジットが返還されます）。
- Name
- api_key_name
- Type
- string
- Description
タスクを実行したAPIキーの表示名。失効したキーについても保持され続けるため、キーのローテーション後も過去の消費を追跡できます。
- Name
- api_key_suffix
- Type
- string
- Description
そのAPIキーの末尾4文字で、同じ名前のキーを区別するために使用します。
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"
}