Usage API

Ilista ang mga natapos na API task ng iyong team at ang credits na ginamit ng bawat isa, para sa billing exports at cost reports.

Para tawagin ang endpoint na ito, gumamit ng API key ng isang aktibong miyembro ng Studio o Enterprise team. Kahit sinong miyembro ang maaaring tumawag nito, hindi lang ang mga owner at admin. Sa anumang ibang API key, ang request ay magbabalik ng 403.

GET/openapi/v1/usage/tasks

Ilista ang mga usage record

Nagbabalik ng isang page ng mga usage record ng iyong team, pinakabago muna bilang default. Kung walang start_time at end_time, sinasaklaw ng mga record ang nakaraang 30 araw. Libre ang pagtawag sa endpoint na ito.

Kasama sa mga record ang mga sumusunod na task:

Mga API task na natapos bilang SUCCEEDED o FAILED
Mga task ng bawat kasalukuyang miyembro ng team, mula sa alinman sa kanilang mga API key
Mga task na dineliyt mo, at mga task na nag-expire na ang mga file

Hindi kasama sa mga record ang mga sumusunod na task:

Mga task na PENDING o IN_PROGRESS pa rin, at mga CANCELED na task
Mga task ng mga taong umalis na sa team
Mga Creative Lab task
Mga task na pinatakbo ng mga AI agent ng Meshy
Gawaing ginawa sa Meshy web app

Lumalabas ang isang task sa mga record lamang pagkatapos itong matapos, sa window ng kanyang created_at. Sisingilin ng Meshy ng credits kapag gumawa ito ng task, kaya mawawala sa mga record ang isang task na tumatakbo pa. Bago mo i-reconcile ang mga record sa iyong credit balanse, kunin muli ang mga kamakailang window, o mag-export pagkatapos ng maikling delay.

Kung may data retention period ang iyong team, ang window ay nagsisimula nang hindi mas maaga kaysa sa pinapayagan ng panahong iyon.

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

Mga Parameter

Name
page_num
Type
integer
default 1
Description
Ang page na ibabalik, mula 1 hanggang 255. Ang value na mas mataas sa 255 ay magbabalik ng 400. Isang window ang maaaring maghawak ng hanggang 255 pages, kaya hatiin ang malaking export sa mas maiikling window.
Name
page_size
Type
integer
default 10
Description
Bilang ng mga record kada page, mula 1 hanggang 100. Ang value mula 101 hanggang 255 ay magbabalik ng 100 record, at ang value na mas mataas sa 255 ay magbabalik ng 400.
Name
sort_by
Type
string
default -created_at
Description
Ang pagkakasunod-sunod ng pag-sort.
Available na mga value:
- +created_at: pinakaluma muna
- -created_at: pinakabago muna
Sa isang URL, isulat ang + bilang %2B. Kung hindi, babasahin ang + bilang espasyo, at magbabalik ang request ng 400.
Name
start_time
Type
string
Description
Ang simula ng window, bilang RFC 3339 timestamp, halimbawa 2026-08-01T00:00:00Z. Kasama sa mga record ang mga task na ginawa sa o pagkatapos ng oras na ito. Iwanang blangko upang simulan ang window 30 araw bago ang end_time.
Ang window ay maaaring sumaklaw ng hanggang 366 araw. Ang mas mahabang window ay magbabalik ng 400, kaya hatiin ang mas mahabang export sa ilang window.
Name
end_time
Type
string
Description
Ang dulo ng window, bilang RFC 3339 timestamp. Kasama sa mga record ang mga task na ginawa bago ang oras na ito. Iwanang blangko upang tapusin ang window sa oras ng iyong request.
Name
endpoints
Type
string
Description
Isang comma-separated na listahan ng mga endpoint na isasama, gamit ang parehong mga pangalan ng field na endpoint. Iwanang blangko upang isama ang bawat endpoint. Ang hindi kilalang pangalan ay magbabalik ng 400.
Available na mga value:
- text-to-3d: bawat Text to 3D task, preview at refine
- text-to-3d-preview: preview tasks lamang
- text-to-3d-refine: refine tasks lamang
- 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
Ang status na isasama, SUCCEEDED o FAILED. Iwanang blangko upang isama ang pareho. Ang ibang value ay magbabalik ng 400.

Ibinabalik

Nagbabalik ng array ng mga usage record. Walang laman ang array kapag walang tumugmang record.

Mga mode ng pagkabigo

Name
400 - Bad Request
Description
May invalid na parameter, at sinasabi ng error message kung alin. Ayusin ang parameter, pagkatapos ay ipadala muli ang request.
Name
401 - Unauthorized
Description
Nawawala o invalid ang API key. Suriin ang Authorization header.
Name
403 - Forbidden
Description
Ang account ng API key ay hindi isang aktibong miyembro ng Studio o Enterprise team. Ang mensahe ay This endpoint is available on Studio and Enterprise plans. Gumamit ng API key ng miyembro ng Studio o Enterprise team.
Name
429 - Too Many Requests
Description
Nagpadala ka ng masyadong maraming request. Hintayin ang bilang ng segundo sa Retry-After, pagkatapos ay subukan muli.

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
Ang task ID, ang parehong ID na ibinalik ng creating endpoint. Upang makuha ang mismong task, kasama ang mga output URL nito, ipadala ang ID sa get route ng endpoint na iyon, halimbawa GET /openapi/v1/image-to-3d/{task_id} para sa isang image-to-3d record.
Name
endpoint
Type
string
Description
Ang endpoint kung saan tumakbo ang task, halimbawa image-to-3d o rig. Ipinapakita ng isang Text to 3D task ang kanyang stage, text-to-3d-preview o text-to-3d-refine.
Ang mga mas lumang record ay maaaring may mga pangalan ng mga retirado na endpoint, na hindi tinatanggap ng endpoints filter.
Name
status
Type
string
Description
Ang pinal na status ng task, SUCCEEDED o FAILED.
Name
created_at
Type
timestamp
Description
Oras na nilikha ang task, sa Unix milliseconds.
Name
finished_at
Type
timestamp
Description
Oras na natapos ang task, sa Unix milliseconds. null kung walang oras ng pagtatapos ang task.
Name
consumed_credits
Type
integer
Description
Bilang ng credits na ginamit ng task, pagkatapos ng mga refund. 0 para sa isang nabigong task, dahil nire-refund ito ng Meshy, at para sa isang libreng task tulad ng Analyze Printability.
Name
api_key_name
Type
string
Description
Ang pangalan ng API key na nagpatakbo ng task. Para sa isang task na pinatakbo gamit ang app login, ito ang pangalan ng app, halimbawa Meshy CLI.
Ito ay walang laman na string sa ilang kaso, halimbawa:
- Hindi kailanman sinisingil ang task, tulad ng isang Analyze Printability task, na libre.
- Nabura na ang API key.
- Ang API key ay ginawa sa nakaraang ilang minuto.
Name
api_key_suffix
Type
string
Description
Ang huling apat na karakter ng API key na iyon, upang matukoy ang pagkakaiba ng mga key na may parehong pangalan. Isang walang-lamang string sa tuwing walang laman ang api_key_name, at para sa mga app login tulad ng Meshy CLI.
Name
metadata
Type
object
Description
Ang mga tag na ipinadala sa X-Meshy-Metadata header noong ginawa ang task. {} kung wala. Tingnan ang Metadata.