Usage API

List your team's finished API tasks and the credits each one used, for billing exports and cost reports.

To call this endpoint, use an API key of an active member of a Studio or Enterprise team. Any member can call it, not only owners and admins. With any other API key, the request returns 403.

GET/openapi/v1/usage/tasks

List usage records

Returns one page of your team's usage records, newest first by default. Without start_time and end_time, the records cover the last 30 days. Calling this endpoint is free.

The records include these tasks:

API tasks that finished as SUCCEEDED or FAILED
Tasks of every current member of the team, from any of their API keys
Tasks you deleted, and tasks whose files have expired

The records leave out these tasks:

Tasks that are still PENDING or IN_PROGRESS, and CANCELED tasks
Tasks of people who have left the team
Creative Lab tasks
Tasks that Meshy's AI agents ran
Work done in the Meshy web app

A task appears in the records only after it finishes, in the window of its created_at. Meshy charges credits when it creates a task, so a task that's still running is missing from the records. Before you reconcile the records with your credit balance, pull recent windows again, or export after a short delay.

If your team has a data retention period, the window starts no earlier than that period allows.

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

Parameters

Name
page_num
Type
integer
default 1
Description
The page to return, from 1 to 255. A value above 255 returns 400. One window holds at most 255 pages, so split a large export into shorter windows.
Name
page_size
Type
integer
default 10
Description
Number of records per page, from 1 to 100. A value from 101 to 255 returns 100 records, and a value above 255 returns 400.
Name
sort_by
Type
string
default -created_at
Description
The sort order.
Available values:
- +created_at: oldest first
- -created_at: newest first
In a URL, write + as %2B. Otherwise the + is read as a space, and the request returns 400.
Name
start_time
Type
string
Description
The start of the window, as an RFC 3339 timestamp, for example 2026-08-01T00:00:00Z. The records include tasks created at or after this time. Leave it out to start the window 30 days before end_time.
The window can span at most 366 days. A longer window returns 400, so split a longer export into several windows.
Name
end_time
Type
string
Description
The end of the window, as an RFC 3339 timestamp. The records include tasks created before this time. Leave it out to end the window at the time of your request.
Name
endpoints
Type
string
Description
A comma-separated list of the endpoints to include, by the same names as the endpoint field. Leave it out to include every endpoint. An unknown name returns 400.
Available values:
- text-to-3d: every Text to 3D task, preview and refine
- text-to-3d-preview: preview tasks only
- text-to-3d-refine: refine tasks only
- 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
The status to include, SUCCEEDED or FAILED. Leave it out to include both. Any other value returns 400.

Returns

Returns an array of usage records. The array is empty when no records match.

Failure modes

Name
400 - Bad Request
Description
A parameter is invalid, and the error message says which one. Fix the parameter, then send the request again.
Name
401 - Unauthorized
Description
The API key is missing or invalid. Check the Authorization header.
Name
403 - Forbidden
Description
The API key's account isn't an active member of a Studio or Enterprise team. The message is This endpoint is available on Studio and Enterprise plans. Use an API key of a Studio or Enterprise team member.
Name
429 - Too Many Requests
Description
You sent too many requests. Wait the number of seconds in Retry-After, then retry.

Usage record object

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
The task ID, the same ID that the creating endpoint returned. To get the task itself, with its output URLs, send the ID to that endpoint's get route, for example GET /openapi/v1/image-to-3d/{task_id} for an image-to-3d record.
Name
endpoint
Type
string
Description
The endpoint the task ran on, for example image-to-3d or rig. A Text to 3D task shows its stage, text-to-3d-preview or text-to-3d-refine.
Older records can have names of retired endpoints, which the endpoints filter doesn't accept.
Name
status
Type
string
Description
The task's final status, SUCCEEDED or FAILED.
Name
created_at
Type
timestamp
Description
Time the task was created, in Unix milliseconds.
Name
finished_at
Type
timestamp
Description
Time the task finished, in Unix milliseconds. null if the task has no finish time.
Name
consumed_credits
Type
integer
Description
Number of credits the task used, after refunds. 0 for a failed task, because Meshy refunds it, and for a free task such as Analyze Printability.
Name
api_key_name
Type
string
Description
The name of the API key that ran the task. For a task run with an app login, it's the app's name, for example Meshy CLI.
It's an empty string in some cases, for example:
- The task was never charged, such as an Analyze Printability task, which is free.
- The API key has been deleted.
- The API key was created in the last few minutes.
Name
api_key_suffix
Type
string
Description
The last four characters of that API key, to tell keys with the same name apart. An empty string whenever api_key_name is empty, and for app logins such as the Meshy CLI.
Name
metadata
Type
object
Description
The tags sent in the X-Meshy-Metadata header when the task was created. {} if none. See Metadata.