Métricas da conta
Last updated
GET /account/metrics retorna estatísticas das consultas da conta autenticada em um intervalo. A leitura não gera cobrança de consulta e não inclui dados pessoais dos resultados.
Requisição
curl 'https://api.verifica-online.com.br/account/metrics?period=30d' \
--header 'Authorization: Bearer <API_KEY>'
As métricas reúnem o consumo de todas as chaves da conta. Para consultá-las, use uma chave ativa. A conta deve atender aos requisitos de acesso.
Intervalos
| Parâmetro | Valores ou formato | Regra |
|---|---|---|
period |
today, 7d, 30d, month, custom |
Opcional; o padrão é 30d. |
from |
ISO 8601 com segundos e fuso explícito | Obrigatório apenas em custom; início inclusivo. |
to |
ISO 8601 com segundos e fuso explícito | Obrigatório apenas em custom; fim inclusivo. |
| Período | Início | Fim |
|---|---|---|
today |
Meia-noite do dia atual em America/Sao_Paulo. |
Momento da leitura. |
7d |
Exatamente 7 dias de 24 horas antes da leitura. | Momento da leitura. |
30d |
Exatamente 30 dias de 24 horas antes da leitura. | Momento da leitura. |
month |
Meia-noite do primeiro dia do mês atual em America/Sao_Paulo. |
Momento da leitura. |
custom |
Valor informado em from. |
Valor informado em to. |
Em custom, a data deve ser válida, o início não pode ser posterior ao fim e o intervalo não pode exceder 366 dias. O formato exige YYYY-MM-DDTHH:mm:ss, admite de uma a três casas decimais nos segundos e exige Z ou deslocamento como -03:00. Datas sem horário ou sem fuso não são aceitas.
Exemplo de intervalo personalizado:
curl --get 'https://api.verifica-online.com.br/account/metrics' \
--header 'Authorization: Bearer <API_KEY>' \
--data-urlencode 'period=custom' \
--data-urlencode 'from=2026-10-01T00:00:00-03:00' \
--data-urlencode 'to=2026-10-02T23:59:59.999-03:00'
O intervalo retornado é convertido para ISO 8601 UTC. Os limites são aplicados à data de criação da consulta, não à data da conclusão ou do débito.
Resposta
Exemplo de um intervalo sem consultas:
{
"metrics": {
"period": "custom",
"from": "2026-10-01T03:00:00.000Z",
"to": "2026-10-03T02:59:59.999Z",
"summary": {
"total": 0,
"succeeded": 0,
"partial": 0,
"no_data": 0,
"failed": 0,
"processing": 0,
"charged_cents": 0,
"discount_cents": 0,
"average_duration_ms": 0,
"p95_duration_ms": 0
},
"by_dataset": [],
"by_day": []
}
}
Campo de metrics |
Tipo | Descrição |
|---|---|---|
period |
string | Período utilizado. |
from |
string | Início inclusivo em UTC. |
to |
string | Fim inclusivo em UTC. |
summary |
object | Totais e durações do intervalo. |
by_dataset |
array de objects | Totais agrupados por dataset com consultas no intervalo. |
by_day |
array de objects | Totais agrupados pelo dia de criação em UTC. |
Resumo
Campo de summary |
Tipo | Descrição |
|---|---|---|
total |
integer | Quantidade de registros de consulta selecionados. |
succeeded |
integer | Quantidade no estado succeeded. |
partial |
integer | Quantidade no estado partial, incluindo parciais gratuitos. |
no_data |
integer | Quantidade no estado no_data. |
failed |
integer | Quantidade no estado failed. |
processing |
integer | Quantidade no estado processing. |
charged_cents |
integer | Soma dos valores já cobrados dessas consultas, em centavos de BRL. |
discount_cents |
integer | Soma dos descontos consolidados, em centavos de BRL. |
average_duration_ms |
integer | Média das durações das consultas concluídas, arredondada em milissegundos. |
p95_duration_ms |
integer | Percentil 95 das durações das consultas concluídas, em milissegundos. |
total é a soma de succeeded, partial, no_data, failed e processing. As durações incluem os quatro estados concluídos e excluem processing. O percentil utiliza as durações ordenadas e a posição ceil(0,95 × quantidade). Sem consultas concluídas, ambas as durações são zero.
A duração registrada não deve ser interpretada como o tempo completo percebido pela aplicação cliente, que pode incluir transmissão, fila e espera por lote.
Agrupamento por dataset
Campo de by_dataset[] |
Tipo | Descrição |
|---|---|---|
dataset |
string | Identificador da modalidade. |
total |
integer | Quantidade de consultas na modalidade. |
succeeded |
integer | Quantidade bem-sucedida. |
partial |
integer | Quantidade com resultado parcial. |
no_data |
integer | Quantidade sem dados. |
failed |
integer | Quantidade com falha. |
processing |
integer | Quantidade em processamento. |
charged_cents |
integer | Soma cobrada na modalidade, em centavos de BRL. |
discount_cents |
integer | Soma dos descontos consolidados, em centavos de BRL. |
A lista segue a ordem do catálogo e contém apenas datasets com registros no intervalo.
Agrupamento diário
Campo de by_day[] |
Tipo | Descrição |
|---|---|---|
date |
string | Dia de criação no formato YYYY-MM-DD, em UTC. |
total |
integer | Quantidade de consultas criadas nesse dia e selecionadas pelo intervalo. |
charged_cents |
integer | Soma dos valores já cobrados dessas consultas. |
Os dias aparecem em ordem cronológica e apenas quando existem registros. O agrupamento usa UTC mesmo nos períodos cujo início é calculado em America/Sao_Paulo; perto da meia-noite, a data de um agrupamento pode diferir da data local.
Consultas, lotes e cobrança
Cada consulta individual criada conta como um registro. Cada item aceito de um lote também conta como uma consulta. O lote não acrescenta um registro extra ao total. Itens rejeitados por entrada inválida ou duplicidade não são incluídos.
Repetições idempotentes, recuperações por GET e leituras de métricas não criam registros de consulta.
Os estados e valores representam os registros no momento da leitura. Um item de lote pode aparecer como succeeded ou partial com cobrança e desconto zero enquanto o lote ainda não foi consolidado. Após a conclusão, esses valores passam a compor as métricas do intervalo em que o item foi criado.
O endpoint apresenta estatísticas de consumo, não um extrato financeiro de recargas, reservas ou estornos. Ele também não representa uma fotografia dos estados existentes exatamente no último instante do intervalo solicitado. O saldo associado a uma operação está descrito em Resultados.
Erros
| HTTP | Código | Situação |
|---|---|---|
422 |
invalid_metrics_period |
Valor de period não reconhecido. |
422 |
invalid_metrics_range |
Limites de custom ausentes, inválidos, invertidos ou superiores a 366 dias. |
Erros de acesso e indisponibilidade seguem o contrato de Erros.