Usage API

A Usage API 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 massa.

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

List Usage Records

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: Ordena por horário de criação em ordem crescente.
- -created_at: Ordena 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 de nomes de endpoints a incluir. Aceita os mesmos valores que o campo de resposta endpoint traz — 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 tanto a fase de preview quanto a de refine. Omita para incluir todos os endpoints.
Name
status
Type
string
Description
Filtra pelo status final da tarefa: SUCCEEDED ou FAILED. Omita para incluir ambos.

Retornos

Retorna uma lista paginada de The Usage Record Objects.

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 está nos resultados dessa janela — reprocesse 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"
  }
]

The Usage Record Object

Name
task_id
Type
string
Description
ID da tarefa que este registro fatura — o mesmo ID retornado pelo endpoint que a criou. Para buscar a tarefa em si (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 diferenciar 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"
}