API de Uso

A API de Uso retorna as tarefas históricas da API da sua equipe, com os créditos que cada uma consumiu. Filtre por janela de tempo, endpoint ou status, e navegue pelas páginas de resultados para exportar em lote.

Disponibilidade. A chave de API deve pertencer a uma equipe Studio ou Enterprise; chaves de qualquer outro plano, ou sem equipe, recebem um 403.

GET/openapi/v1/usage/tasks

Listar Registros de Uso

Retorna uma página das tarefas de API da equipe, das mais recentes para as mais antigas. Sem um intervalo de tempo explícito, a resposta cobre os últimos 30 dias.

Parâmetros

Name
page_num
Type
integer
padrão 1
Description
Número da página para paginação.
Name
page_size
Type
integer
padrão 10
Description
Limite de tamanho da página. O máximo permitido é 100 itens.
Name
sort_by
Type
string
padrão -created_at
Description
Campo pelo qual ordenar.
Valores disponíveis:
- +created_at: Ordenar por horário de criação em ordem crescente.
- -created_at: Ordenar por horário de criação em ordem decrescente.
Name
start_time
Type
string
Description
Início da janela de created_at, como um carimbo de data/hora RFC 3339 (ex.: 2026-08-01T00:00:00Z). O padrão é 30 dias antes de end_time. A janela pode abranger no máximo 1 ano — para exportações maiores, navegue por janelas consecutivas.
Name
end_time
Type
string
Description
Fim da janela de created_at, como um carimbo de data/hora RFC 3339. O padrão é o horário atual.
Name
endpoints
Type
string
Description
Lista separada por vírgulas dos nomes de endpoint a incluir. Aceita os mesmos valores que o campo de resposta endpoint carrega — 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 — onde text-to-3d é um termo abrangente que cobre as fases de preview e refine. Omita para incluir todos os endpoints.
Name
status
Type
string
Description
Filtre pelo status final da tarefa: SUCCEEDED ou FAILED. Omita para incluir ambos.

Retornos

Retorna uma lista paginada de Objetos de Registro de Uso.

Os registros cobrem tarefas que atingiram um status final. Os créditos são cobrados quando uma tarefa é criada, então uma tarefa ainda em execução no momento da exportação ainda não aparece nos resultados dessa janela — refaça a busca de janelas recentes (ou exporte com um pequeno atraso) se seus totais precisarem corresponder exatamente ao seu saldo de créditos.

Equipes com uma política de retenção de dados personalizada recebem registros dentro da sua janela de retenção 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"
  }
]

O Objeto de Registro de Uso

Name
task_id
Type
string
Description
ID da tarefa que este registro cobra — o mesmo ID retornado pelo endpoint de criação. Para buscar a própria tarefa (incluindo seu modelo de saída ou URLs de imagem, ressignados a cada leitura), passe-o para o endpoint de recuperação correspondente, ex.: GET /openapi/v1/{endpoint}/{task_id}.
Name
endpoint
Type
string
Description
O endpoint no qual a tarefa foi executada, ex.: image-to-3d ou text-to-3d-refine. Tarefas de Texto para 3D reportam sua fase (text-to-3d-preview / text-to-3d-refine).
Name
status
Type
string
Description
Status final da tarefa: SUCCEEDED ou FAILED.
Name
created_at
Type
timestamp
Description
Carimbo de data/hora da criação da tarefa, em milissegundos.
Name
finished_at
Type
timestamp
Description
Carimbo de data/hora da conclusão, em milissegundos. null se a tarefa não tiver um horário de conclusão.
Name
consumed_credits
Type
integer
Description
Créditos consumidos por esta tarefa. Retorna 0 para tarefas FAILED (os créditos são reembolsados em caso de falha).
Name
api_key_name
Type
string
Description
Nome de exibição da chave de API que executou a tarefa. Permanece preenchido para chaves revogadas, de modo que os gastos históricos continuem atribuíveis após a rotação de chaves.
Name
api_key_suffix
Type
string
Description
Os últimos quatro caracteres dessa chave de API, para distinguir chaves com o mesmo nome.

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