Usage API

Usage API mengembalikan riwayat tugas API tim Anda beserta kredit yang dikonsumsi 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 tim, dimulai dari yang terbaru. Tanpa rentang waktu eksplisit, respons mencakup 30 hari terakhir.

Parameter

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 diizinkan 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.
- -created_at: Urutkan berdasarkan waktu pembuatan secara menurun.
Name
start_time
Type
string
Description
Awal rentang created_at, sebagai stempel waktu RFC 3339 (mis. 2026-08-01T00:00:00Z). Defaultnya adalah 30 hari sebelum end_time. Rentang dapat mencakup maksimal 1 tahun — untuk ekspor yang lebih besar, telusuri rentang yang berurutan per halaman.
Name
end_time
Type
string
Description
Akhir rentang created_at, sebagai stempel waktu RFC 3339. Defaultnya adalah waktu saat ini.
Name
endpoints
Type
string
Description
Daftar nama endpoint yang disertakan, dipisahkan koma. Menerima nilai yang sama dengan yang dibawa 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, print-split — di mana text-to-3d adalah payung yang mencakup 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.

Rekaman mencakup tugas yang telah mencapai status akhir. Kredit dikenakan saat tugas dibuat, sehingga tugas yang masih berjalan saat Anda mengekspor belum masuk dalam hasil rentang tersebut — tarik ulang rentang terbaru (atau ekspor dengan sedikit penundaan) jika total Anda harus sama persis dengan saldo kredit Anda.

Tim dengan kebijakan retensi data khusus menerima rekaman 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 rekaman ini — ID yang sama dengan yang dikembalikan endpoint pembuatnya. Untuk mengambil tugas itu sendiri (termasuk URL model atau gambar hasilnya, 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 dicabut, sehingga riwayat pengeluaran tetap dapat ditelusuri setelah rotasi kunci.
Name
api_key_suffix
Type
string
Description
Empat karakter terakhir dari kunci API tersebut, untuk membedakan 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"
}