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

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