Usage API

Usage APIは、チームの過去のAPIタスクと、それぞれが消費したクレジットを返します。時間範囲、エンドポイント、またはステータスでフィルタリングし、結果をページ送りして一括エクスポートできます。

利用可否について。 APIキーはStudioまたはEnterpriseチームに属している必要があります。それ以外のプランのキー、またはチームに属していないキーは403を受け取ります。

GET/openapi/v1/usage/tasks

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 — ここでtext-to-3dはpreviewとrefineの両フェーズを包括する上位区分です。省略するとすべてのエンドポイントが対象になります。
Name
status
Type
string
Description
終了ステータスでフィルタリングします: SUCCEEDEDまたはFAILED。省略すると両方が対象になります。

戻り値

The Usage Record Objectsのページネーションされたリストを返します。

レコードは終了ステータスに達したタスクを対象とします。クレジットはタスクの作成時に課金されるため、エクスポート時点でまだ実行中のタスクは、その時間範囲の結果にはまだ含まれません。合計値をクレジット残高と厳密に一致させる必要がある場合は、直近の範囲を再取得するか（あるいは少し遅らせてからエクスポートするか）してください。

カスタムのデータ保持ポリシーを持つチームは、設定された保持期間内のレコードを受け取ります。

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"
  },
  {
    "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を含み、読み取りのたびに再署名されます）には、対応する取得エンドポイントにこのIDを渡します。例: 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"
}