# Logs (referência)

## GET `/v1/projects/{p}/services/{s}/logs`

Log de execução do serviço

Lê o log do container a partir de `since` (omitido = final do log) e `cursor`. Segredos são mascarados.

Escopo exigido: `logs:read`.

Escopo exigido: `logs:read` · operationId: `getRuntimeLogs`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço dentro do projeto. |
| `since` | query | string | não | Instante RFC 3339 a partir do qual ler o log de execução. |
| `cursor` | query | string | não | Cursor opaco devolvido em `next_cursor` da leitura anterior. |

### Resposta 200

Trecho do log.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `text` | string | sim | Trecho de log (segredos mascarados). |
| `next_cursor` | string | sim | Passe em `cursor` para continuar; vazio = ainda sem mais dados. |
| `done` | boolean | sim | `true` quando não haverá mais log (build terminado). |

```json
{
  "text": "Step 1/5 : FROM node:22\n",
  "next_cursor": "MTI4",
  "done": false
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## GET `/v1/projects/{p}/services/{s}/deployments/{d}/logs`

Log de build do deployment

Lê o log de build a partir de `cursor` (vazio = início). Continue com `next_cursor` até `done=true`. Segredos são mascarados.

Escopo exigido: `logs:read`.

Escopo exigido: `logs:read` · operationId: `getBuildLogs`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço dentro do projeto. |
| `d` | path | string | sim | Id do deployment (do serviço da rota). |
| `cursor` | query | string | não | Cursor opaco devolvido em `next_cursor` da leitura anterior. |

### Resposta 200

Trecho do log.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `text` | string | sim | Trecho de log (segredos mascarados). |
| `next_cursor` | string | sim | Passe em `cursor` para continuar; vazio = ainda sem mais dados. |
| `done` | boolean | sim | `true` quando não haverá mais log (build terminado). |

```json
{
  "text": "Step 1/5 : FROM node:22\n",
  "next_cursor": "MTI4",
  "done": false
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.