VolundOS
Referência da APIGovernança

Ler consumo de sistema de IA de terceiro

Consumo agregado do período, por assento (group_by=seat) ou pelo total do ativo (group_by=asset). No total do ativo, o rateio não atribuído vem em coluna separada: somado ao consumo por assento, viraria consumo de gente. A janela é obrigatória e não tem default: uma janela implícita faria a mesma chamada devolver números diferentes conforme o dia. Além do escopo, exige da identidade da chave a permissão third_party_usage_view. Exige o escopo governance:read.

Atualizado em 21 de setembro de 2026
GET
/v1/governance/usage

Authorization

chaveDeApi
AuthorizationBearer <token>

Chave de API da organização, criada nas configurações. Envie-a em Authorization: Bearer <sua chave>.

In: header

Query Parameters

asset_id?string

Identificador do ativo. Informe asset_id ou external_ref.

external_ref?string

Referência externa do ativo.

asset_type?string

Tipo do ativo, para desambiguar external_ref.

period_kind?string

day (padrão) ou month. São dois relatos do mesmo consumo: somar os dois conta o dobro.

Default"day"

Value in

  • "day"
  • "month"
from*string

Início da janela, YYYY-MM-DD.

Formatdate
to*string

Fim da janela, YYYY-MM-DD.

Formatdate
group_by?string

seat (padrão), project ou asset.

Default"seat"

Value in

  • "seat"
  • "project"
  • "asset"
dimension?string

Por pessoa (seat) ou por projeto (project). OBRIGATÓRIA com group_by=asset, e sem valor padrão: as duas dimensões são dois relatos do mesmo consumo, e escolher uma em silêncio devolveria metade do total do ativo sem dizer que é metade. Com group_by=seat ou project a dimensão vem dali, e um valor que contradiga o recorte é recusado.

Value in

  • "seat"
  • "project"
metric_key?string

Filtra por uma métrica do vocabulário.

Value in

  • "usage_credit"
  • "usage_token"
  • "usage_request"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/governance/usage?from=2019-08-24&to=2019-08-24"
{  "asset_id": "string",  "group_by": "seat",  "dimension": "seat",  "seats": [    {      "seat_id": "string",      "external_user_key": "string",      "email": "string",      "display_name": "string",      "user_id": "string",      "match_method": "string",      "seat_status": "string",      "quota_limit": 0,      "quota_unit": "string",      "metric_key": "string",      "unit": "string",      "quantity": 0,      "cost_usd": 0,      "periods": 0    }  ]}

Ingerir consumo de sistema de IA de terceiro

Recebe assentos e consumo de um ativo em lote, numa única transação. Reenviar o mesmo lote não duplica: a resposta separa received de created, e é essa diferença que evidencia a idempotência. Um lote pode declarar replace_period para afirmar que é o relato completo do que cobre; nesse caso batch_id é obrigatório, porque é ele que identifica a rodada e impede a substituição de apagar o que a própria rodada acabou de gravar. Além do escopo, exige da identidade da chave a permissão third_party_usage_manage: o consumo por assento é dado individual de cada pessoa. Exige o escopo governance:write.

Listar assentos de um sistema de IA de terceiro

Os assentos do ativo. unmatched=true devolve só os que não foram correspondidos a um membro — a licença que a organização paga e não consegue atribuir a ninguém, que é o achado de governança. A resposta traz truncated: sem ele, uma lista que bateu no teto seria indistinguível de uma lista completa. Além do escopo, exige da identidade da chave a permissão third_party_usage_view. Exige o escopo governance:read.