Usage API

Ibinabalik ng Usage API ang mga makasaysayang API task ng iyong team kasama ang credits na ginugol ng bawat isa. Mag-filter ayon sa time window, endpoint, o status, at mag-page sa mga resulta para mag-export nang bulk.

Availability. Ang API key ay dapat kabilang sa isang Studio o Enterprise team; ang mga key sa ibang plan, o walang team, ay makakatanggap ng 403.

GET/openapi/v1/usage/tasks

List Usage Records

Nagbabalik ng isang page ng mga API task ng team, pinakabago muna. Kung walang tahasang time range, sinasaklaw ng tugon ang huling 30 araw.

Mga Parameter

Name
page_num
Type
integer
default 1
Description
Numero ng page para sa pagination.
Name
page_size
Type
integer
default 10
Description
Limitasyon sa laki ng page. Ang pinakamataas na pinapayagan ay 100 items.
Name
sort_by
Type
string
default -created_at
Description
Field na gagamitin sa pag-uuri.
Mga available na value:
- +created_at: Umuuri ayon sa oras ng paglikha nang pataas (ascending).
- -created_at: Umuuri ayon sa oras ng paglikha nang pababa (descending).
Name
start_time
Type
string
Description
Simula ng created_at window, bilang RFC 3339 timestamp (hal. 2026-08-01T00:00:00Z). Nagde-default sa 30 araw bago ang end_time. Ang window ay maaaring sumaklaw ng hanggang 1 taon lamang — para sa mas malalaking export, mag-page sa magkakasunod na window.
Name
end_time
Type
string
Description
Katapusan ng created_at window, bilang RFC 3339 timestamp. Nagde-default sa kasalukuyang oras.
Name
endpoints
Type
string
Description
Listahan ng mga pangalan ng endpoint na pinaghihiwalay ng kuwit na isasama. Tumatanggap ng parehong mga value na dala ng response field na 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 — kung saan ang text-to-3d ay isang payong na sumasaklaw sa parehong preview at refine na yugto. Iwanang walang laman para isama ang bawat endpoint.
Name
status
Type
string
Description
Mag-filter ayon sa terminal na status ng task: SUCCEEDED o FAILED. Iwanang walang laman para isama ang pareho.

Ibinabalik

Nagbabalik ng paginated na listahan ng The Usage Record Objects.

Sinasaklaw ng mga record ang mga task na nakarating na sa terminal na status. Sinisingil ang credits kapag nalikha ang isang task, kaya ang isang task na tumatakbo pa habang nag-e-export ka ay wala pa sa mga resulta ng window na iyon — muling kunin ang mga kamakailang window (o mag-export nang may maikling pagkaantala) kung kailangang eksaktong tumugma ang iyong mga kabuuan sa iyong balanse ng credits.

Ang mga team na may custom na patakaran sa pagpapanatili ng data ay makakatanggap ng mga record sa loob ng kanilang naka-configure na 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 ng task na sinisingil ng record na ito — ang parehong ID na ibinalik ng endpoint na lumikha nito. Para kunin ang task mismo (kabilang ang output model nito o mga URL ng imahe, muling nilagdaan sa bawat pagbasa), ipasa ito sa kaukulang retrieve endpoint, hal. GET /openapi/v1/{endpoint}/{task_id}.
Name
endpoint
Type
string
Description
Ang endpoint kung saan tumakbo ang task, hal. image-to-3d o text-to-3d-refine. Ang mga Text to 3D task ay nagre-report ng kanilang yugto (text-to-3d-preview / text-to-3d-refine).
Name
status
Type
string
Description
Terminal na status ng task: SUCCEEDED o FAILED.
Name
created_at
Type
timestamp
Description
Timestamp ng paglikha ng task, sa milliseconds.
Name
finished_at
Type
timestamp
Description
Timestamp ng pagkumpleto, sa milliseconds. null kung ang task ay walang dalang oras ng pagkumpleto.
Name
consumed_credits
Type
integer
Description
Credits na ginugol ng task na ito. Nagbabalik ng 0 para sa mga FAILED na task (nire-refund ang credits kapag nabigo).
Name
api_key_name
Type
string
Description
Display name ng API key na nagpatakbo ng task. Nananatiling naka-populate para sa mga na-revoke na key, kaya ang makasaysayang paggastos ay nananatiling matutukoy pagkatapos ng pag-rotate ng key.
Name
api_key_suffix
Type
string
Description
Huling apat na character ng API key na iyon, para makilala ang mga key na may parehong pangalan.

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