Usage API

Usage API mengembalikan riwayat tugas API tim Anda beserta kredit yang dikonsumsi oleh masing-masing tugas. Filter berdasarkan rentang waktu, endpoint, atau status, dan telusuri hasilnya per halaman untuk diekspor secara massal.

Ketersediaan. Kunci API harus dimiliki oleh tim Studio atau Enterprise; kunci pada paket lain, atau tanpa tim, akan menerima 403.

GET/openapi/v1/usage/tasks

List Usage Records

Mengembalikan satu halaman tugas API milik tim, dari yang terbaru ke yang terlama. Tanpa rentang waktu eksplisit, respons mencakup 30 hari terakhir.

Parameters

Name
page_num
Type
integer
default 1
Description
Nomor halaman untuk paginasi.
Name
page_size
Type
integer
default 10
Description
Batas ukuran halaman. Maksimum yang diperbolehkan adalah 100 item.
Name
sort_by
Type
string
default -created_at
Description
Kolom yang digunakan untuk pengurutan.
Nilai yang tersedia:
- +created_at: Urutkan berdasarkan waktu pembuatan secara menaik (ascending).
- -created_at: Urutkan berdasarkan waktu pembuatan secara menurun (descending).
Name
start_time
Type
string
Description
Awal rentang created_at, sebagai stempel waktu RFC 3339 (mis. 2026-08-01T00:00:00Z). Secara default, 30 hari sebelum end_time. Rentang dapat mencakup paling banyak 1 tahun — untuk ekspor yang lebih besar, telusuri rentang-rentang berurutan per halaman.
Name
end_time
Type
string
Description
Akhir rentang created_at, sebagai stempel waktu RFC 3339. Secara default, waktu saat ini.
Name
endpoints
Type
string
Description
Daftar nama endpoint yang akan disertakan, dipisahkan koma. Menerima nilai yang sama seperti yang dibawa oleh kolom respons 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 — di mana text-to-3d merupakan payung yang mencakup baik fase preview maupun refine. Kosongkan untuk menyertakan semua endpoint.
Name
status
Type
string
Description
Filter berdasarkan status akhir tugas: SUCCEEDED atau FAILED. Kosongkan untuk menyertakan keduanya.

Returns

Mengembalikan daftar berpaginasi dari The Usage Record Objects.

Rekam data mencakup tugas yang telah mencapai status akhir. Kredit dikenakan saat tugas dibuat, sehingga tugas yang masih berjalan saat Anda melakukan ekspor belum termasuk dalam hasil rentang tersebut — tarik ulang rentang terbaru (atau ekspor dengan sedikit jeda) jika total Anda harus sesuai persis dengan saldo kredit Anda.

Tim dengan kebijakan retensi data khusus akan menerima rekam data dalam jendela retensi yang telah dikonfigurasi.

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 tugas yang ditagih oleh rekam data ini — ID yang sama dengan yang dikembalikan oleh endpoint pembuatnya. Untuk mengambil tugas itu sendiri (termasuk URL model atau gambar keluarannya, yang ditandatangani ulang di setiap pembacaan), teruskan ID tersebut ke endpoint pengambilan yang sesuai, mis. GET /openapi/v1/{endpoint}/{task_id}.
Name
endpoint
Type
string
Description
Endpoint tempat tugas dijalankan, mis. image-to-3d atau text-to-3d-refine. Tugas Teks ke 3D melaporkan fasenya (text-to-3d-preview / text-to-3d-refine).
Name
status
Type
string
Description
Status akhir tugas: SUCCEEDED atau FAILED.
Name
created_at
Type
timestamp
Description
Stempel waktu pembuatan tugas, dalam milidetik.
Name
finished_at
Type
timestamp
Description
Stempel waktu penyelesaian, dalam milidetik. null jika tugas tidak membawa waktu penyelesaian.
Name
consumed_credits
Type
integer
Description
Kredit yang dikonsumsi oleh tugas ini. Mengembalikan 0 untuk tugas FAILED (kredit dikembalikan jika gagal).
Name
api_key_name
Type
string
Description
Nama tampilan kunci API yang menjalankan tugas. Tetap terisi untuk kunci yang telah dicabut, sehingga pengeluaran historis tetap dapat dilacak setelah rotasi kunci.
Name
api_key_suffix
Type
string
Description
Empat karakter terakhir dari kunci API tersebut, untuk membedakan kunci-kunci dengan nama yang sama.

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