Usage API

Usage API mengembalikan riwayat task API tim Anda beserta kredit yang dikonsumsi masing-masing. 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 lainnya, atau tanpa tim, akan menerima 403.

GET/openapi/v1/usage/tasks

List Usage Records

Mengembalikan satu halaman task API tim, dengan yang terbaru terlebih dahulu. 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 untuk mengurutkan.
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 (misalnya 2026-08-01T00:00:00Z). Default-nya 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. Default-nya adalah waktu saat ini.
Name
endpoints
Type
string
Description
Daftar nama endpoint yang dipisahkan koma untuk disertakan. 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 — di mana text-to-3d merupakan payung yang mencakup fase preview maupun refine. Kosongkan untuk menyertakan semua endpoint.
Name
status
Type
string
Description
Filter berdasarkan status akhir task: SUCCEEDED atau FAILED. Kosongkan untuk menyertakan keduanya.

Returns

Mengembalikan daftar berpaginasi dari The Usage Record Objects.

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

Tim dengan kebijakan retensi data kustom menerima rekaman dalam rentang 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 task yang ditagih oleh rekaman ini — ID yang sama dengan yang dikembalikan oleh endpoint pembuatnya. Untuk mengambil task itu sendiri (termasuk model output atau URL gambar-nya, ditandatangani ulang setiap kali dibaca), berikan ID tersebut ke endpoint pengambilan yang sesuai, misalnya GET /openapi/v1/{endpoint}/{task_id}.
Name
endpoint
Type
string
Description
Endpoint tempat task dijalankan, misalnya image-to-3d atau text-to-3d-refine. Task Teks ke 3D melaporkan fasenya (text-to-3d-preview / text-to-3d-refine).
Name
status
Type
string
Description
Status akhir task: SUCCEEDED atau FAILED.
Name
created_at
Type
timestamp
Description
Stempel waktu pembuatan task, dalam milidetik.
Name
finished_at
Type
timestamp
Description
Stempel waktu penyelesaian, dalam milidetik. null jika task tidak memiliki waktu penyelesaian.
Name
consumed_credits
Type
integer
Description
Kredit yang dikonsumsi oleh task ini. Mengembalikan 0 untuk task FAILED (kredit dikembalikan jika gagal).
Name
api_key_name
Type
string
Description
Nama tampilan kunci API yang menjalankan task. Tetap terisi untuk kunci yang telah dicabut, sehingga pengeluaran historis 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"
}