Usage API

チームの完了済みAPIタスクと、それぞれが使用したクレジットを一覧取得し、請求エクスポートやコストレポートに利用できます。

このエンドポイントを呼び出すには、StudioまたはEnterpriseチームのアクティブなメンバーのAPIキーを使用してください。オーナーや管理者に限らず、どのメンバーでも呼び出せます。それ以外のAPIキーでリクエストすると、403が返されます。

GET/openapi/v1/usage/tasks

使用記録の一覧取得

チームの使用記録を1ページ分返します。デフォルトでは新しい順です。start_timeとend_timeを指定しない場合、記録は直近30日分を対象とします。このエンドポイントの呼び出しは無料です。

記録には以下のタスクが含まれます。

SUCCEEDEDまたはFAILEDとして完了したAPIタスク
チームの現メンバー全員のタスク（どのAPIキーからのものでも）
削除したタスクや、ファイルの有効期限が切れたタスク

記録には以下のタスクは含まれません。

まだPENDINGまたはIN_PROGRESSのタスク、およびCANCELEDのタスク
チームを離脱した人のタスク
Creative Labのタスク
MeshyのAIエージェントが実行したタスク
Meshyのウェブアプリで行った作業

タスクは完了して初めて記録に表示され、そのcreated_atの時刻を含むウィンドウに現れます。Meshyはタスクを作成した時点でクレジットを課金するため、まだ実行中のタスクは記録に現れません。記録をクレジット残高と突き合わせる前に、直近のウィンドウを再度取得するか、少し時間をおいてからエクスポートしてください。

チームにデータ保持期間が設定されている場合、ウィンドウの開始はその期間が許す範囲より前にはなりません。

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

パラメータ

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: preview・refineを含むすべてのテキストから3Dタスク
- text-to-3d-preview: previewタスクのみ
- text-to-3d-refine: 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
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）。テキストから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
タスクが使用したクレジット数（返金後）です。失敗したタスクの場合は0です。これはMeshyが返金するためで、プリント可能性を分析のような無料のタスクの場合も同様に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を参照してください。