Usage API
チームで完了したAPIタスクと、各タスクで消費したクレジットを一覧表示します。請求のエクスポートやコストレポートにご利用ください。
このエンドポイントを呼び出すには、StudioまたはEnterpriseチームの有効なメンバーのAPIキーを使用してください。オーナーや管理者に限らず、どのメンバーでも呼び出せます。それ以外のAPIキーでリクエストすると、403が返されます。
使用状況レコードの一覧取得
チームの使用状況レコードを1ページ分返します。デフォルトでは新しい順です。start_timeとend_timeを指定しない場合、レコードは過去30日分が対象になります。このエンドポイントの呼び出しは無料です。
レコードには次のタスクが含まれます。
SUCCEEDEDまたはFAILEDで終了したAPIタスク- チームの現在のすべてのメンバーのタスク(どのAPIキーからのものでも)
- 削除済みのタスクや、ファイルの有効期限が切れたタスク
レコードには次のタスクは含まれません。
- まだ
PENDINGまたはIN_PROGRESSのタスク、およびCANCELEDのタスク - チームを離脱した人のタスク
- Creative Labのタスク
- MeshyのAIエージェントが実行したタスク
- Meshyウェブアプリ内で行った作業
タスクは完了してはじめて、そのcreated_atの属するウィンドウ内にレコードとして表示されます。Meshyはタスク作成時にクレジットを課金するため、実行中のタスクはレコードにまだ現れません。レコードとクレジット残高を突き合わせる前に、最近のウィンドウを再取得するか、少し時間を置いてからエクスポートしてください。
チームにデータ保持期間が設定されている場合、ウィンドウの開始時刻はその期間が許す範囲より前には遡りません。
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",
"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": {}
}
]
パラメータ
- Name
- page_num
- Type
- integer
- デフォルト 1
- Description
返すページ番号で、
1から255の範囲です。255を超える値を指定すると400が返されます。1つのウィンドウには最大255ページまで保持されるため、大きなエクスポートはより短いウィンドウに分割してください。
- Name
- page_size
- Type
- integer
- デフォルト 10
- Description
1ページあたりのレコード数で、
1から100の範囲です。101から255の値を指定すると100件が返され、255を超える値を指定すると400が返されます。
- Name
- sort_by
- Type
- string
- デフォルト -created_at
- Description
並び順です。
利用可能な値:
+created_at:古い順-created_at:新しい順
URL内では、
+は%2Bと記述してください。そうしないと+が空白として解釈され、リクエストが400を返します。
- Name
- start_time
- Type
- string
- Description
ウィンドウの開始時刻を、RFC 3339形式のタイムスタンプで指定します(例:
2026-08-01T00:00:00Z)。この時刻以降に作成されたタスクがレコードに含まれます。省略すると、end_timeの30日前からウィンドウが開始されます。ウィンドウは最大366日まで指定できます。これより長いウィンドウを指定すると
400が返されるため、長いエクスポートは複数のウィンドウに分割してください。
- Name
- end_time
- Type
- string
- Description
ウィンドウの終了時刻を、RFC 3339形式のタイムスタンプで指定します。この時刻より前に作成されたタスクがレコードに含まれます。省略すると、リクエスト時刻がウィンドウの終了時刻になります。
- Name
- endpoints
- Type
- string
- Description
含めるエンドポイントをカンマ区切りで指定します。名前は
endpointフィールドと同じものを使用します。省略するとすべてのエンドポイントが含まれます。不明な名前を指定すると400が返されます。利用可能な値:
text-to-3d:すべてのText to 3Dタスク(previewとrefineの両方)text-to-3d-preview:previewタスクのみtext-to-3d-refine:refineタスクのみimage-to-3dmulti-image-to-3dretextureremeshconvertresizeuv-unwrapriganimatetext-to-motiontext-to-imageimage-to-imageprint-multi-colorprint-repairprint-analyzeprint-splitrelief
- Name
- status
- Type
- string
- Description
含めるステータスで、
SUCCEEDEDまたはFAILEDです。省略すると両方が含まれます。それ以外の値を指定すると400が返されます。
返り値
使用状況レコードの配列を返します。一致するレコードがない場合、配列は空になります。
失敗時の挙動
- Name
400 - Bad Request- Description
いずれかのパラメータが無効です。エラーメッセージにどのパラメータかが示されます。該当のパラメータを修正してから、リクエストを再送してください。
- Name
401 - Unauthorized- Description
APIキーが指定されていないか、無効です。
Authorizationヘッダーを確認してください。
- Name
403 - Forbidden- Description
APIキーのアカウントが、StudioまたはEnterpriseチームの有効なメンバーではありません。メッセージは
This endpoint is available on Studio and Enterprise plansです。StudioまたはEnterpriseチームのメンバーのAPIキーを使用してください。
- Name
429 - Too Many Requests- Description
リクエストを送りすぎました。
Retry-Afterに示された秒数だけ待ってから、再試行してください。
使用状況レコードオブジェクト
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
タスクIDで、作成元のエンドポイントが返したものと同じIDです。出力URLを含むタスク自体を取得するには、このIDをそのエンドポイントの取得用ルートに送信します。例えば
image-to-3dのレコードであればGET /openapi/v1/image-to-3d/{task_id}です。
- Name
- endpoint
- Type
- string
- Description
タスクが実行されたエンドポイントで、例えば
image-to-3dやrigです。Text to 3Dタスクの場合は、そのステージであるtext-to-3d-previewまたはtext-to-3d-refineが表示されます。古いレコードには、廃止されたエンドポイントの名前が含まれている場合があり、これらは
endpointsフィルターでは受け付けられません。
- Name
- status
- Type
- string
- Description
タスクの最終ステータスで、
SUCCEEDEDまたはFAILEDです。
- Name
- created_at
- Type
- timestamp
- Description
タスクが作成された時刻で、Unixミリ秒形式です。
- Name
- finished_at
- Type
- timestamp
- Description
タスクが完了した時刻で、Unixミリ秒形式です。タスクに完了時刻がない場合は
nullです。
- Name
- consumed_credits
- Type
- integer
- Description
タスクが消費したクレジット数で、返金後の値です。タスクが失敗した場合はMeshyが返金するため
0になります。また、プリント可能性を分析のような無料タスクも0です。
- Name
- api_key_name
- Type
- string
- Description
タスクを実行したAPIキーの名前です。アプリのログインで実行されたタスクの場合は、そのアプリの名前(例:
Meshy CLI)になります。次のような場合は空文字列になります。
- プリント可能性を分析のタスクのように、そもそも課金されなかったタスク(無料のため)。
- APIキーが削除されている場合。
- APIキーが数分以内に作成されたばかりの場合。
- Name
- api_key_suffix
- Type
- string
- Description
そのAPIキーの末尾4文字で、同じ名前のキーを区別するためのものです。
api_key_nameが空文字列の場合は常に空文字列になり、Meshy CLIのようなアプリログインの場合も同様です。
- Name
- metadata
- Type
- object
- Description
タスク作成時に
X-Meshy-Metadataヘッダーで送信されたタグです。何もない場合は{}です。詳細はMetadataを参照してください。