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-адреса изображений, повторно подписываемые при каждом чтении), передайте этот ID в соответствующий эндпоинт получения, например 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"
}