Usage API
Usage APIは、チームの過去のAPIタスクと、各タスクで消費されたクレジットを返します。時間範囲、エンドポイント、またはステータスでフィルタし、結果をページ送りして一括エクスポートできます。
利用可否について。 APIキーはStudioまたはEnterpriseチームに属している必要があります。それ以外のプランのキー、またはチームに属していないキーは403を受け取ります。
List Usage Records
チームのAPIタスクを1ページ分、新しい順に返します。明示的な時間範囲を指定しない場合、レスポンスは直近30日分をカバーします。
Parameters
- 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— ここでtext-to-3dはpreviewフェーズとrefineフェーズの両方を包括する上位カテゴリです。省略するとすべてのエンドポイントが含まれます。
- Name
- status
- Type
- string
- Description
終端タスクステータスでフィルタします:
SUCCEEDEDまたはFAILED。省略すると両方が含まれます。
Returns
Usage Recordオブジェクトのページネーションされたリストを返します。
レコードは終端ステータスに達したタスクをカバーします。クレジットはタスク作成時に課金されるため、エクスポート時にまだ実行中のタスクはその時間範囲の結果にはまだ含まれません — 合計値をクレジット残高と厳密に一致させる必要がある場合は、直近の時間範囲を再取得するか（または短い遅延を設けてエクスポートしてください）。
カスタムのデータ保持ポリシーを持つチームは、設定された保持期間内のレコードを受け取ります。
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}。
- 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"
}