Usage API

Lihat daftar tugas API tim Anda yang telah selesai beserta jumlah kredit yang digunakan masing-masing, untuk keperluan ekspor penagihan dan laporan biaya.

Untuk memanggil endpoint ini, gunakan kunci API dari anggota aktif tim Studio atau Enterprise. Setiap anggota dapat memanggilnya, tidak hanya pemilik dan admin. Dengan kunci API lain, permintaan akan mengembalikan 403.

GET/openapi/v1/usage/tasks

Daftar catatan penggunaan

Mengembalikan satu halaman catatan penggunaan tim Anda, secara default diurutkan dari yang terbaru. Tanpa start_time dan end_time, catatan mencakup 30 hari terakhir. Memanggil endpoint ini tidak dikenakan biaya.

Catatan ini mencakup tugas-tugas berikut:

Tugas API yang selesai dengan status SUCCEEDED atau FAILED
Tugas dari setiap anggota tim yang masih aktif, dari kunci API mana pun milik mereka
Tugas yang telah Anda hapus, dan tugas yang filenya sudah kedaluwarsa

Catatan ini tidak mencakup tugas-tugas berikut:

Tugas yang masih berstatus PENDING atau IN_PROGRESS, dan tugas berstatus CANCELED
Tugas dari orang yang sudah keluar dari tim
Tugas Creative Lab
Tugas yang dijalankan oleh agen AI Meshy
Pekerjaan yang dilakukan di aplikasi web Meshy

Sebuah tugas muncul dalam catatan hanya setelah tugas tersebut selesai, dalam rentang waktu created_at-nya. Meshy mengenakan biaya kredit saat membuat tugas, sehingga tugas yang masih berjalan tidak akan muncul dalam catatan. Sebelum mencocokkan catatan dengan saldo kredit Anda, ambil ulang rentang waktu terbaru, atau lakukan ekspor setelah jeda singkat.

Jika tim Anda memiliki periode retensi data, rentang waktu tidak akan dimulai lebih awal dari yang diizinkan periode tersebut.

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

Parameter

Name
page_num
Type
integer
default 1
Description
Halaman yang akan dikembalikan, dari 1 hingga 255. Nilai di atas 255 akan mengembalikan 400. Satu rentang waktu menampung paling banyak 255 halaman, jadi bagi ekspor besar menjadi rentang waktu yang lebih pendek.
Name
page_size
Type
integer
default 10
Description
Jumlah catatan per halaman, dari 1 hingga 100. Nilai dari 101 hingga 255 akan mengembalikan 100 catatan, dan nilai di atas 255 akan mengembalikan 400.
Name
sort_by
Type
string
default -created_at
Description
Urutan pengurutan.
Nilai yang tersedia:
- +created_at: terlama lebih dulu
- -created_at: terbaru lebih dulu
Dalam URL, tulis + sebagai %2B. Jika tidak, + akan dibaca sebagai spasi, dan permintaan akan mengembalikan 400.
Name
start_time
Type
string
Description
Awal rentang waktu, sebagai stempel waktu RFC 3339, misalnya 2026-08-01T00:00:00Z. Catatan mencakup tugas yang dibuat pada atau setelah waktu ini. Kosongkan untuk memulai rentang waktu 30 hari sebelum end_time.
Rentang waktu dapat mencakup paling banyak 366 hari. Rentang waktu yang lebih panjang akan mengembalikan 400, jadi bagi ekspor yang lebih panjang menjadi beberapa rentang waktu.
Name
end_time
Type
string
Description
Akhir rentang waktu, sebagai stempel waktu RFC 3339. Catatan mencakup tugas yang dibuat sebelum waktu ini. Kosongkan untuk mengakhiri rentang waktu pada waktu permintaan Anda.
Name
endpoints
Type
string
Description
Daftar endpoint yang akan disertakan, dipisahkan koma, menggunakan nama yang sama dengan field endpoint. Kosongkan untuk menyertakan semua endpoint. Nama yang tidak dikenali akan mengembalikan 400.
Nilai yang tersedia:
- text-to-3d: semua tugas Teks ke 3D, preview dan refine
- text-to-3d-preview: hanya tugas preview
- text-to-3d-refine: hanya tugas 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
Name
status
Type
string
Description
Status yang akan disertakan, SUCCEEDED atau FAILED. Kosongkan untuk menyertakan keduanya. Nilai lain akan mengembalikan 400.

Hasil

Mengembalikan sebuah array berisi catatan penggunaan. Array akan kosong jika tidak ada catatan yang cocok.

Mode kegagalan

Name
400 - Bad Request
Description
Salah satu parameter tidak valid, dan pesan error menunjukkan parameter mana. Perbaiki parameter tersebut, lalu kirim ulang permintaan.
Name
401 - Unauthorized
Description
Kunci API tidak ada atau tidak valid. Periksa header Authorization.
Name
403 - Forbidden
Description
Akun kunci API bukan anggota aktif tim Studio atau Enterprise. Pesannya adalah This endpoint is available on Studio and Enterprise plans. Gunakan kunci API dari anggota tim Studio atau Enterprise.
Name
429 - Too Many Requests
Description
Anda mengirim terlalu banyak permintaan. Tunggu sejumlah detik sesuai Retry-After, lalu coba lagi.

Objek catatan penggunaan

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
ID tugas, yaitu ID yang sama dengan yang dikembalikan oleh endpoint pembuatnya. Untuk mendapatkan tugas itu sendiri, beserta URL outputnya, kirim ID tersebut ke rute get milik endpoint itu, misalnya GET /openapi/v1/image-to-3d/{task_id} untuk catatan image-to-3d.
Name
endpoint
Type
string
Description
Endpoint tempat tugas dijalankan, misalnya image-to-3d atau rig. Tugas Teks ke 3D menampilkan tahapannya, text-to-3d-preview atau text-to-3d-refine.
Catatan lama dapat memiliki nama endpoint yang sudah tidak digunakan lagi, yang tidak diterima oleh filter endpoints.
Name
status
Type
string
Description
Status akhir tugas, SUCCEEDED atau FAILED.
Name
created_at
Type
timestamp
Description
Waktu tugas dibuat, dalam milidetik Unix.
Name
finished_at
Type
timestamp
Description
Waktu tugas selesai, dalam milidetik Unix. null jika tugas tidak memiliki waktu selesai.
Name
consumed_credits
Type
integer
Description
Jumlah kredit yang digunakan tugas, setelah pengembalian dana. 0 untuk tugas yang gagal, karena Meshy mengembalikan dananya, dan untuk tugas gratis seperti Analisis kemampuan cetak.
Name
api_key_name
Type
string
Description
Nama kunci API yang menjalankan tugas tersebut. Untuk tugas yang dijalankan melalui login aplikasi, nilainya adalah nama aplikasi tersebut, misalnya Meshy CLI.
Nilainya berupa string kosong dalam beberapa kasus, misalnya:
- Tugas tersebut tidak pernah dikenakan biaya, seperti tugas Analisis kemampuan cetak, yang gratis.
- Kunci API tersebut telah dihapus.
- Kunci API tersebut dibuat dalam beberapa menit terakhir.
Name
api_key_suffix
Type
string
Description
Empat karakter terakhir dari kunci API tersebut, untuk membedakan kunci dengan nama yang sama. Berupa string kosong setiap kali api_key_name kosong, dan untuk login aplikasi seperti Meshy CLI.
Name
metadata
Type
object
Description
Tag yang dikirim dalam header X-Meshy-Metadata saat tugas dibuat. {} jika tidak ada. Lihat Metadata.