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

# Consultando logs

Busque linhas de log com a [API pública (V2)](/api/v2/overview). Esta é a forma de
consultar logs programaticamente, incluindo dados de log estruturados (JSON). A API
GraphQL não expõe linhas de log.

<Tip>
  Se você está construindo um agente ou assistente de IA, o [AppSignal MCP](/mcp-server)
  expõe a busca de logs e outros dados de monitoramento diretamente aos agentes, sem
  precisar chamar esta API por conta própria.
</Tip>

## Encontrando seus IDs de site e fonte

Uma busca em logs precisa de um `site_id` e um ou mais `source_ids`. Ambos aparecem na
URL de uma fonte de log na AppSignal. Abra uma fonte de log e leia-os no path:

<CodeGroup>
  ```text URL theme={null}
  https://appsignal.com/<organization>/sites/<SITE_ID>/logs/sources/<SOURCE_ID>
  ```
</CodeGroup>

## Buscar linhas de log

<CodeGroup>
  ```shell Endpoint theme={null}
  POST /api/v2/logs/lines
  ```
</CodeGroup>

### Corpo da requisição

| Campo             | Tipo              | Obrigatório | Descrição                                                                             |
| ----------------- | ----------------- | ----------- | ------------------------------------------------------------------------------------- |
| `site_id`         | string            | Sim         | Site a ser consultado.                                                                |
| `source_ids`      | string\[]         | Sim         | IDs de fonte de log a serem buscados. Pelo menos um é obrigatório.                    |
| `query`           | string            | Sim         | String de query que filtra linhas de log. Veja [linguagem de query](#query-language). |
| `use_expressions` | boolean           | Não         | Quando `true`, parseia `query` com a linguagem de query baseada em expressões.        |
| `from`            | string (ISO 8601) | Não         | Início do intervalo de tempo. Padrão é o limite inferior de retenção.                 |
| `to`              | string (ISO 8601) | Não         | Fim do intervalo de tempo. Padrão é o horário atual.                                  |
| `pagination`      | object            | Sim         | Cursor e direção da paginação (veja a seção a seguir).                                |

Defina `use_expressions` como `true` para usar a linguagem de query baseada em expressões
documentada nesta página.

`pagination` recebe `per_page` (número), `order` (`ASC` ou `DESC`) e um `cursor`
com um campo `time` (um timestamp ISO 8601, ou `null` na primeira página). Para
buscar a próxima página, envie o timestamp da última linha recebida como
`cursor.time` da próxima requisição.

### Exemplo de requisição

<CodeGroup>
  ```shell cURL theme={null}
  curl --request POST \
    --url "https://appsignal.com/api/v2/logs/lines" \
    --header "Authorization: Bearer YOUR-PERSONAL-API-TOKEN" \
    --header "Content-Type: application/json" \
    --data @body.json
  ```
</CodeGroup>

<CodeGroup>
  ```json body.json theme={null}
  {
    "site_id": "YOUR-SITE-ID",
    "source_ids": ["YOUR-LOG-SOURCE-ID"],
    "query": "severity=error status_code=401",
    "use_expressions": true,
    "from": "2026-06-22T00:00:00Z",
    "to": "2026-06-22T23:59:59Z",
    "pagination": {
      "per_page": 100,
      "order": "DESC",
      "cursor": { "time": null }
    }
  }
  ```
</CodeGroup>

### Resposta

O endpoint retorna um array de linhas de log. Cada linha inclui estes campos:

| Campo        | Tipo              | Descrição                                                                    |
| ------------ | ----------------- | ---------------------------------------------------------------------------- |
| `id`         | string            | Identificador da linha de log.                                               |
| `timestamp`  | string (ISO 8601) | Quando a linha de log foi registrada.                                        |
| `source_id`  | string            | Fonte de log a que a linha pertence.                                         |
| `severity`   | string            | Nível de severidade, como `info` ou `error`.                                 |
| `message`    | string            | O corpo da mensagem de log.                                                  |
| `hostname`   | string            | Host que produziu a linha.                                                   |
| `group`      | string            | Grupo de log.                                                                |
| `json`       | string            | O corpo estruturado (JSON) bruto da linha de log, quando disponível.         |
| `attributes` | object            | Atributos chave-valor tipados legados. Sendo descontinuado — prefira `json`. |

<Note>
  Campos estruturados como `status_code`, `path` ou `detail` vivem no campo `json`,
  não em `attributes`. Consulte-os pela chave exata como aparece no JSON do seu
  log (por exemplo, `status_code=401` ou `detail.message:"required"`).
</Note>

## Linguagem de query

Quando `use_expressions` é `true`, a string `query` suporta lógica booleana sobre
campos da linha de log e o corpo `json` estruturado.

### Operadores

| Operador | Nome           | Comportamento                      |
| -------- | -------------- | ---------------------------------- |
| `=`      | Igual          | Correspondência exata.             |
| `!=`     | Diferente      | Não correspondência exata.         |
| `:`      | Contém         | Correspondência por substring.     |
| `!:`     | Não contém     | Não correspondência por substring. |
| `>`      | Maior que      | Comparação numérica.               |
| `>=`     | Maior ou igual | Comparação numérica.               |
| `<`      | Menor que      | Comparação numérica.               |
| `<=`     | Menor ou igual | Comparação numérica.               |

Operadores de string (`=`, `!=`, `:`, `!:`) comparam ambos os lados como strings. Operadores
numéricos (`>`, `>=`, `<`, `<=`) convertem ambos os lados em número; se um valor não puder ser
parseado como número, aquela linha de log é ignorada.

### Combinando expressões

* **AND / OR:** `severity=error AND hostname:web`, ou `severity=info OR severity=warn`.
* **AND implícito:** um espaço entre expressões significa AND. `severity=error hostname:web` é o mesmo que `severity=error AND hostname:web`.
* **Aninhamento com parênteses:** `message:"API request" AND (severity=info OR severity=warn)`.
* **Precedência:** AND tem precedência maior que OR.

Qualquer operador pode ser usado dentro de um grupo `OR`, não só igualdade — por exemplo,
`message:"API request" AND (user.id>1000 OR user.email:"example.com")`.

### Campos

Dada uma linha de log com este corpo JSON:

<CodeGroup>
  ```json Example log theme={null}
  {
    "message": "API request completed",
    "severity": "info",
    "duration": 156.7,
    "status_code": 200,
    "user": {
      "id": 12345,
      "roles": ["admin", "developer"],
      "location.country": "US"
    }
  }
  ```
</CodeGroup>

* **Campos base:** `message`, `severity`, `hostname` e `group` correspondem aos campos de nível superior da linha de log.
* **JSON aninhado:** use notação de ponto para alcançar dentro do corpo `json`, como `status_code=200` ou `user.id=12345`.
* **Arrays JSON:** indexe elementos do array, como `user.roles.0=admin`.
* **Pontos escapados:** para corresponder a um ponto literal em um nome de chave, escape-o. `user.location\.country=US` corresponde à chave `location.country` dentro de `user`, em vez de um objeto `country` aninhado.
* **Campo padrão:** um termo isolado sem campo corresponde a `message` com o operador `contains`. `timeout` é o mesmo que `message:timeout`.

Você não precisa prefixar com `attributes.` nem adicionar um sufixo de tipo para consultar um campo
— referencie-o diretamente pelo nome. Veja [sintaxe de query
legada](#legacy-query-syntax) se você tem queries mais antigas.

### Aspas em valores

Envolva valores que contêm espaços ou parênteses entre aspas duplas. Caso contrário, o
espaço divide o valor em expressões separadas unidas por AND implícito.

```text theme={null}
message:"hello world"           matches message containing "hello world"
message:hello world             parsed as message:hello AND message:world
severity=error message:"oh no"  severity equals error AND message contains "oh no"
```

Apenas aspas duplas são reconhecidas. Dentro de um valor entre aspas, escape uma aspa com
`\"` e uma barra invertida com `\\`. Por exemplo, `message:"value with \"quotes\""`
corresponde ao texto `value with "quotes"`.

### Sintaxe de query legada

Queries mais antigas armazenavam atributos como campos tipados, então precisavam prefixar
`attributes.`, adicionar um sufixo de tipo (`_string`, `_int`) e usar uma lista `[ ]` para
múltiplos valores. A linguagem de query atual remove todas as três — referencie campos
diretamente e use `OR` em vez de uma lista:

<CodeGroup>
  ```text Old query theme={null}
  message:"API request" attributes.user_id_int=12345 severity=[info, warn]
  ```

  ```text New query theme={null}
  message:"API request" user.id=12345 (severity=info OR severity=warn)
  ```
</CodeGroup>

Uma query que ainda usa a sintaxe legada retorna `422` com o slug de erro
`legacy_log_query_syntax`.