Usage API

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

Availability. Ang API key ay dapat pagmamay-ari ng isang Studio o Enterprise team; ang mga key sa ibang plano, o walang team, ay tatanggap ng 403.

GET/openapi/v1/usage/tasks

Ilistang ang mga Talaan ng Paggamit

Ibinabalik ang isang page ng mga API task ng team, pinakabago muna. Kung walang tahasang time range, sinasaklaw ng response 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-sort.
Mga available na value:
- +created_at: Isaayos ayon sa oras ng paglikha nang pataas.
- -created_at: Isaayos ayon sa oras ng paglikha nang pababa.
Name
start_time
Type
string
Description
Simula ng created_at window, bilang RFC 3339 timestamp (hal. 2026-08-01T00:00:00Z). Ang default ay 30 araw bago ang end_time. Ang window ay maaaring umabot ng hanggang 1 taon — para sa mas malalaking export, mag-page sa mga sunod-sunod na window.
Name
end_time
Type
string
Description
Katapusan ng created_at window, bilang RFC 3339 timestamp. Default ay ang kasalukuyang oras.
Name
endpoints
Type
string
Description
Listahan ng mga pangalan ng endpoint na pinaghihiwalay ng kuwit na isasama. Tinatanggap ang 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, print-split — kung saan ang text-to-3d ay isang pangkalahatang termino na sumasaklaw sa parehong preview at refine phase. Iwan itong walang laman para isama ang lahat ng endpoint.
Name
status
Type
string
Description
Mag-filter ayon sa terminal na status ng task: SUCCEEDED o FAILED. Iwan itong walang laman para isama ang dalawa.

Mga Ibabalik

Ibinabalik ang isang paginated na listahan ng Mga Object ng Talaan ng Paggamit.

Sinasaklaw ng mga talaan ang mga task na nakaabot sa terminal status. Sinisingil ang credits kapag nalikha ang isang task, kaya ang isang task na tumatakbo pa habang nag-eeksport ka ay hindi pa kasama sa mga resulta ng window na iyon — kunin muli ang mga kamakailang window (o mag-export nang may maikling delay) kung dapat tumugma ang iyong mga kabuuan sa iyong credit balanse nang eksakto.

Ang mga team na may custom na patakaran sa data-retention ay tumatanggap ng mga talaan sa loob ng kanilang naitakdang 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"
  }
]

Ang Object ng Talaan ng Paggamit

Name
task_id
Type
string
Description
ID ng task na sisingilin ng talaang ito — ang parehong ID na ibinalik ng endpoint na lumikha nito. Para kunin ang task mismo (kasama 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. Iniuulat ng mga Text to 3D task ang kanilang phase (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 natupok ng task na ito. Nagbabalik ng 0 para sa mga FAILED task (nirefund ang credits kung mabigo).
Name
api_key_name
Type
string
Description
Display na pangalan ng API key na nagpatakbo ng task. Nananatiling puno ang laman kahit sa mga na-revoke na key, para manatiling matukoy ang historikal na gastos kahit pagkatapos ng key rotation.
Name
api_key_suffix
Type
string
Description
Huling apat na character ng API key na iyon, para maiba 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"
}