> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kinglog.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Consultar dados

> Perguntas de lista, contagem e indicador usam schema, consulta, agregação e métricas. Tudo é somente leitura.

Perguntas como “quantas”, “quais”, “por responsável” ou “neste mês” passam pelo motor de consulta. O assistente não escreve SQL. A API valida o pedido e aplica empresa, permissão e escopo.

Entidades consultáveis:

`tasks`, `projects`, `clients`, `leads`, `crm_activities`, `helpdesk_tickets`, `sprints`, `sla_commitments`, `organizations`, `contacts`.

## Descobrir o schema

`kinglog_discover_schema` sem `entity` lista todas. Com `entity`, detalha campos, tipos, operadores, relações, agregações e limites. Campo fora do alcance da conta aparece como `access=forbidden`.

Chame a descoberta antes de montar um filtro novo.

## Listar

`kinglog_query_data` recebe `entity` e um `query` opcional:

* `fields`: até 40 campos
* `include`: relações, com até 20 campos em cada uma
* `where`: valor direto significa igual. Também aceita `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`, `contains`, `startsWith`, `endsWith`, `between`, `isNull`, `AND`, `OR` e `NOT`
* `orderBy`: até 4 campos, `ASC` ou `DESC`
* `pagination`: `offset` ou `cursor`, `limit` de 1 a 500

Em campo de usuário, `"@me"` é a pessoa da sessão. Exemplo de intenção: tarefas em que eu sou o responsável.

```json theme={null}
{
  "entity": "tasks",
  "query": {
    "where": { "responsibleId": "@me" },
    "pagination": { "type": "offset", "page": 1, "limit": 20 }
  }
}
```

A resposta pode trazer `meta.truncated`, `meta.warnings` e `meta.scopeApplied`. Vale citar isso quando o recorte mudou o resultado. Em `QUERY_INVALID`, a mensagem lista os campos válidos: o assistente corrige e repete.

## Agregar

`kinglog_aggregate_data` serve para contagem, soma, média, mínimo e máximo. Ela agrupa; não devolve a lista de registros.

* `metrics`: de 1 a 20, com `op` em `count`, `sum`, `avg`, `min`, `max`
* `groupBy`: até 8, inclusive relação 1:1 como `status.name`, e `timeBucket` em `day`, `week`, `month`, `quarter` ou `year`
* `limit`: de 1 a 1000

## Métricas prontas

`kinglog_metrics` sem `metric` lista as definições e os parâmetros. Com `metric`, calcula e devolve `value`, `values`, `definition`, `criteria`, `period` e `caveats`. A resposta ao usuário deve carregar a definição, porque o número sozinho omite o critério.

| Id | Nome |
| - | - |
| `tasks.overdue` | Tarefas atrasadas |
| `tasks.completion_rate` | Taxa de conclusão de tarefas |
| `tasks.workload_by_responsible` | Carga de trabalho por responsável |
| `projects.health` | Saúde dos projetos |
| `crm.stale_leads` | Leads parados |
| `crm.conversion_rate` | Taxa de conversão do CRM |
| `helpdesk.open_by_priority` | Tickets abertos por prioridade |
| `sla.compliance` | Cumprimento de SLA |

Parâmetros de usuário, como `responsibleId`, aceitam `@me`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.