API de uso

La API de uso devuelve las tareas históricas de la API de tu equipo junto con los créditos que cada una consumió. Filtra por ventana de tiempo, endpoint o estado, y recorre los resultados por páginas para exportarlos en bloque.

Disponibilidad. La clave de API debe pertenecer a un equipo Studio o Enterprise; las claves de cualquier otro plan, o sin equipo, reciben un 403.

GET/openapi/v1/usage/tasks

Listar registros de uso

Devuelve una página de las tareas de la API del equipo, empezando por las más recientes. Sin un rango de tiempo explícito, la respuesta cubre los últimos 30 días.

Parámetros

Name
page_num
Type
integer
predeterminado 1
Description
Número de página para la paginación.
Name
page_size
Type
integer
predeterminado 10
Description
Límite de tamaño de página. El máximo permitido es 100 elementos.
Name
sort_by
Type
string
predeterminado -created_at
Description
Campo por el que ordenar.
Valores disponibles:
- +created_at: Ordenar por hora de creación de forma ascendente.
- -created_at: Ordenar por hora de creación de forma descendente.
Name
start_time
Type
string
Description
Inicio de la ventana de created_at, como marca de tiempo RFC 3339 (por ejemplo, 2026-08-01T00:00:00Z). Por defecto, 30 días antes de end_time. La ventana puede abarcar como máximo 1 año; para exportaciones más grandes, recorre ventanas consecutivas por páginas.
Name
end_time
Type
string
Description
Fin de la ventana de created_at, como marca de tiempo RFC 3339. Por defecto, la hora actual.
Name
endpoints
Type
string
Description
Lista separada por comas de nombres de endpoints a incluir. Acepta los mismos valores que lleva el campo de respuesta 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 — donde text-to-3d es una categoría que abarca tanto la fase preview como la fase refine. Omítelo para incluir todos los endpoints.
Name
status
Type
string
Description
Filtra por estado final de la tarea: SUCCEEDED o FAILED. Omítelo para incluir ambos.

Devuelve

Devuelve una lista paginada de Los objetos de registro de uso.

Los registros cubren tareas que han alcanzado un estado final. Los créditos se cobran al crear una tarea, así que una tarea que aún esté en ejecución cuando exportes no aparecerá todavía en los resultados de esa ventana; vuelve a extraer las ventanas recientes (o exporta con un pequeño retraso) si tus totales deben coincidir exactamente con tu saldo de créditos.

Los equipos con una política de retención de datos personalizada reciben los registros dentro de su ventana de retención configurada.

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

El objeto de registro de uso

Name
task_id
Type
string
Description
ID de la tarea que este registro factura — el mismo ID que devolvió el endpoint que la creó. Para obtener la tarea en sí (incluyendo su modelo de salida o las URL de imagen, re-firmadas en cada lectura), pásalo al endpoint de recuperación correspondiente, por ejemplo GET /openapi/v1/{endpoint}/{task_id}.
Name
endpoint
Type
string
Description
El endpoint en el que se ejecutó la tarea, por ejemplo image-to-3d o text-to-3d-refine. Las tareas de Texto a 3D indican su fase (text-to-3d-preview / text-to-3d-refine).
Name
status
Type
string
Description
Estado final de la tarea: SUCCEEDED o FAILED.
Name
created_at
Type
timestamp
Description
Marca de tiempo de la creación de la tarea, en milisegundos.
Name
finished_at
Type
timestamp
Description
Marca de tiempo de finalización, en milisegundos. null si la tarea no lleva una hora de finalización.
Name
consumed_credits
Type
integer
Description
Créditos consumidos por esta tarea. Devuelve 0 para las tareas FAILED (los créditos se reembolsan en caso de fallo).
Name
api_key_name
Type
string
Description
Nombre visible de la clave de API que ejecutó la tarea. Permanece completado incluso para claves revocadas, de modo que el gasto histórico siga siendo atribuible después de rotar las claves.
Name
api_key_suffix
Type
string
Description
Los últimos cuatro caracteres de esa clave de API, para distinguir claves con el mismo nombre.

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