Usage API

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

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

GET/openapi/v1/usage/tasks

List Usage Records

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

Parameters

  • 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 є загальною категорією, що охоплює обидві фази: preview і refine. Не вказуйте, щоб включити всі кінцеві точки.

  • Name
    status
    Type
    string
    Description

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

Returns

Повертає пагінований список 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"
}