Usage API

Ang Usage API ay nagbabalik ng history ng mga API task ng iyong team kasama ang credits na ginamit ng bawat isa. I-filter ayon sa time window, endpoint, o status, at mag-page sa mga resulta para i-export nang bulk.

Availability. Dapat ang API key ay pag-aari ng isang Studio o Enterprise team; ang mga key sa ibang plano, o walang team, ay makakatanggap ng 403.

GET/openapi/v1/usage/tasks

Ilista ang mga Usage Record

Ibinabalik ang isang page ng mga API task ng team, pinakabago muna. Kung walang tahasang time range, sasaklawin ng response ang huling 30 araw.

Parameters

Name
page_num
Type
integer
default 1
Description
Numero ng page para sa pagination.
Name
page_size
Type
integer
default 10
Description
Limitasyon ng page size. Ang maximum na pinapayagan ay 100 items.
Name
sort_by
Type
string
default -created_at
Description
Field na gagamitin sa pag-sort.
Available na mga value:
- +created_at: I-sort ayon sa oras ng paggawa nang ascending.
- -created_at: I-sort ayon sa oras ng paggawa nang descending.
Name
start_time
Type
string
Description
Simula ng created_at window, bilang RFC 3339 timestamp (hal. 2026-08-01T00:00:00Z). Default ay 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. Default ay kasalukuyang oras.
Name
endpoints
Type
string
Description
Listahan ng mga pangalan ng endpoint na isasama, pinaghihiwalay ng kuwit. Tumatanggap ng parehong mga value na dala ng endpoint response field — 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 umbrella na sumasaklaw sa parehong preview at refine phase. Iwanang blangko para isama ang lahat ng endpoint.
Name
status
Type
string
Description
I-filter ayon sa terminal task status: SUCCEEDED o FAILED. Iwanang blangko 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 status. Sinisingil ang credits kapag nagawa ang isang task, kaya ang 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 dapat na eksaktong tumugma ang iyong mga total sa iyong credit balance.

Ang mga team na may custom na data-retention policy ay tumatanggap ng mga record sa loob ng na-configure nilang 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 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 gumawa nito. Para kunin ang task mismo (kabilang ang output model nito o mga URL ng imahe, muling na-sign 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 phase (text-to-3d-preview / text-to-3d-refine).
Name
status
Type
string
Description
Terminal task status: SUCCEEDED o FAILED.
Name
created_at
Type
timestamp
Description
Timestamp ng paggawa 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 ginamit ng task na ito. Nagbabalik ng 0 para sa mga FAILED na task (irerefund ang credits kapag nabigo).
Name
api_key_name
Type
string
Description
Display name ng API key na nagpatakbo ng task. Nananatiling naka-populate kahit para sa mga na-revoke na key, kaya ang historic na paggasta ay maiuugnay pa rin pagkatapos ng key rotation.
Name
api_key_suffix
Type
string
Description
Huling apat na karakter 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"
}