Usage API

Usage API повертає історичні API-завдання вашої команди разом із кредитами, витраченими на кожне з них. Фільтруйте за часовим вікном, кінцевою точкою або статусом і гортайте сторінки результатів для масового експорту.

Доступність. API-ключ має належати команді на плані Studio або Enterprise; ключі на будь-якому іншому плані, або без команди, отримують 403.

GET/openapi/v1/usage/tasks

List Usage Records

Повертає одну сторінку API-завдань команди, спочатку найновіші. Без явно заданого часового діапазону відповідь охоплює останні 30 днів.

Параметри

  • Name
    page_num
    Type
    integer
    за замовчуванням 1
    Description

    Номер сторінки для пагінації.

  • Name
    page_size
    Type
    integer
    за замовчуванням 10
    Description

    Обмеження розміру сторінки. Максимально допустиме значення — 100 елементів.

  • Name
    sort_by
    Type
    string
    за замовчуванням -created_at
    Description

    Поле для сортування.

    Доступні значення:

    • +created_at: Сортування за часом створення в порядку зростання.
    • -created_at: Сортування за часом створення в порядку спадання.
  • Name
    start_time
    Type
    string
    Description

    Початок вікна created_at, у форматі мітки часу RFC 3339 (наприклад, 2026-08-01T00:00:00Z). За замовчуванням — 30 днів до end_time. Вікно може охоплювати щонайбільше 1 рік — для більших експортів гортайте послідовні вікна.

  • Name
    end_time
    Type
    string
    Description

    Кінець вікна created_at, у форматі мітки часу RFC 3339. За замовчуванням — поточний час.

  • Name
    endpoints
    Type
    string
    Description

    Список назв кінцевих точок через кому, які потрібно включити. Приймає ті самі значення, що й поле відповіді 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 — де text-to-3d є загальною назвою, що охоплює обидві фази: попередній перегляд і доопрацювання. Не вказуйте, щоб включити всі кінцеві точки.

  • Name
    status
    Type
    string
    Description

    Фільтр за фінальним статусом завдання: SUCCEEDED або FAILED. Не вказуйте, щоб включити обидва.

Повертає

Повертає розбитий на сторінки список об'єктів The Usage Record Objects.

Записи охоплюють завдання, що досягли фінального статусу. Кредити списуються під час створення завдання, тому завдання, яке все ще виконується на момент вашого експорту, ще не потрапляє в результати цього вікна — повторно завантажуйте останні вікна (або експортуйте з невеликою затримкою), якщо ваші підсумкові суми мають точно відповідати вашому балансу кредитів.

Команди з власною політикою зберігання даних отримують записи в межах налаштованого вікна зберігання.

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 завдання, за яке виставлено рахунок у цьому записі — той самий ID, який повернула кінцева точка створення. Щоб отримати саме завдання (включно з URL-адресами вихідної моделі або зображення, які повторно підписуються при кожному читанні), передайте його у відповідну кінцеву точку отримання, напр. GET /openapi/v1/{endpoint}/{task_id}.

  • Name
    endpoint
    Type
    string
    Description

    Кінцева точка, на якій виконувалось завдання, напр. image-to-3d або text-to-3d-refine. Завдання Текст у 3D повідомляють свою фазу (text-to-3d-preview / text-to-3d-refine).

  • Name
    status
    Type
    string
    Description

    Фінальний статус завдання: SUCCEEDED або FAILED.

  • Name
    created_at
    Type
    timestamp
    Description

    Мітка часу створення завдання, у мілісекундах.

  • Name
    finished_at
    Type
    timestamp
    Description

    Мітка часу завершення, у мілісекундах. null, якщо завдання не містить часу завершення.

  • Name
    consumed_credits
    Type
    integer
    Description

    Кредити, витрачені на це завдання. Повертає 0 для завдань зі статусом FAILED (у разі невдачі кредити повертаються).

  • Name
    api_key_name
    Type
    string
    Description

    Відображуване ім'я API-ключа, який виконав завдання. Залишається заповненим навіть для відкликаних ключів, тож історичні витрати залишаються відстежуваними після ротації ключів.

  • Name
    api_key_suffix
    Type
    string
    Description

    Останні чотири символи цього API-ключа, щоб відрізняти ключі з однаковою назвою.

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