Usage API

The Usage API returns your team's historic API tasks with the credits each one consumed. Filter by time window, endpoint, or status, and page through the results to export in bulk.

Availability. The API key must belong to a Studio or Enterprise team; keys on any other plan, or with no team, receive a 403.

GET/openapi/v1/usage/tasks

List Usage Records

Returns one page of the team's API tasks, newest first. Without an explicit time range, the response covers the last 30 days.

Parameters

Name
page_num
Type
integer
default 1
Description
Page number for pagination.
Name
page_size
Type
integer
default 10
Description
Page size limit. Maximum allowed is 100 items.
Name
sort_by
Type
string
default -created_at
Description
Field to sort by.
Available values:
- +created_at: Sort by creation time in ascending order.
- -created_at: Sort by creation time in descending order.
Name
start_time
Type
string
Description
Start of the created_at window, as an RFC 3339 timestamp (e.g. 2026-08-01T00:00:00Z). Defaults to 30 days before end_time. The window may span at most 1 year — for larger exports, page through consecutive windows.
Name
end_time
Type
string
Description
End of the created_at window, as an RFC 3339 timestamp. Defaults to the current time.
Name
endpoints
Type
string
Description
Comma-separated list of endpoint names to include. Accepts the same values the endpoint response field carries — 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 — where text-to-3d is an umbrella covering both the preview and refine phases. Omit to include every endpoint.
Name
status
Type
string
Description
Filter by terminal task status: SUCCEEDED or FAILED. Omit to include both.

Returns

Returns a paginated list of The Usage Record Objects.

Records cover tasks that have reached a terminal status. Credits are charged when a task is created, so a task still running when you export is not in that window's results yet — re-pull recent windows (or export with a short delay) if your totals must match your credit balance exactly.

Teams with a custom data-retention policy receive records within their configured retention window.

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 of the task this record bills — the same ID the creating endpoint returned. To fetch the task itself (including its output model or image URLs, re-signed on every read), pass it to the corresponding retrieve endpoint, e.g. GET /openapi/v1/{endpoint}/{task_id}.
Name
endpoint
Type
string
Description
The endpoint the task ran on, e.g. image-to-3d or text-to-3d-refine. Text to 3D tasks report their phase (text-to-3d-preview / text-to-3d-refine).
Name
status
Type
string
Description
Terminal task status: SUCCEEDED or FAILED.
Name
created_at
Type
timestamp
Description
Timestamp of task creation, in milliseconds.
Name
finished_at
Type
timestamp
Description
Timestamp of completion, in milliseconds. null if the task carries no completion time.
Name
consumed_credits
Type
integer
Description
Credits consumed by this task. Returns 0 for FAILED tasks (credits are refunded on failure).
Name
api_key_name
Type
string
Description
Display name of the API key that ran the task. Stays populated for revoked keys, so historic spend remains attributable after key rotation.
Name
api_key_suffix
Type
string
Description
Last four characters of that API key, for telling keys with the same name apart.

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"
}