> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/documentation/pt-br/painel/dashboard-api.md).

# API do Painel

Acesso programático aos usuários dos produtos da Oxylabs para acompanhar estatísticas de uso com a API do Painel.

A **Dashboard API** permite que você **acesse suas estatísticas de uso do produto** programaticamente e integre as métricas aos seus sistemas internos. Isso permite relatórios automatizados e monitoramento de uso em tempo real sem usar o dashboard da Oxylabs na web.

{% hint style="info" %}
**Observação:** Dashboard API atualmente suporta **Datacenter Proxies (DC**) e **Headless Browser (HB)**. Você também pode acompanhar [**Residential Proxies**](/products/pt-br/proxies/residential-proxies/public-api.md), [**Mobile Proxies**](/products/pt-br/proxies/mobile-proxies/public-api.md), [**Web Unblocker**](/products/pt-br/web-unblocker/usage-statistics.md), e [**Web Scraper API**](/products/pt-br/web-scraper-api/usage-and-billing/usage-statistics.md) estatísticas de uso com simples solicitações à API.
{% endhint %}

Todas as solicitações à API passam por este caminho base:

```
https://api.oxylabs.io/
```

## Autenticação

{% hint style="warning" %}
**Importante:** Para obter sua chave da Dashboard API, entre em contato com nossa [**Equipe de Suporte ao Cliente**](mailto:support@oxylabs.io) equipe. Assim que solicitada, a chave será gerada e entregue diretamente a você em até um dia útil.
{% endhint %}

Você deve incluir a chave no cabeçalho `Authorization` de cada solicitação usando o esquema `Bearer` .

```
Authorization: Bearer {YOUR_API_KEY}
```

## Endpoints

A Dashboard API inclui endpoints para Descoberta de instâncias e Estatísticas de uso do produto. Todas as respostas são entregues em formato JSON.

<table><thead><tr><th width="236.8125">Endpoint</th><th>Descrição</th></tr></thead><tbody><tr><td><a href="#instance-discovery">descoberta de instâncias</a></td><td>A solicitação retorna uma lista paginada das instâncias do produto às quais sua conta está autorizada a acessar. Você pode usar os IDs retornados para filtrar os resultados ao chamar outros endpoints.</td></tr><tr><td><a href="#usage-statistics">estatísticas de uso</a></td><td>A solicitação retorna estatísticas agregadas de uso por produto para as instâncias de produto do cliente autenticado.</td></tr></tbody></table>

### Descoberta de instâncias

```
GET /stats/v1/filters/instances
```

#### Parâmetros de consulta

<table><thead><tr><th width="166">Parâmetro</th><th width="268.0481770833333">Descrição</th><th>Tipo</th></tr></thead><tbody><tr><td><code>products[]</code></td><td>Filtre por produto. Valores aceitos: <code>HB</code> (Headless Browser), <code>DC</code> (Datacenter Proxies), <code>null</code> (todos os produtos).</td><td>Vetor de strings</td></tr><tr><td><code>página</code></td><td>Número da página. Padrão: <code>1</code>.</td><td>Inteiro</td></tr><tr><td><code>por_page</code></td><td>Resultados por página. Padrão: <code>100</code>. Máximo: <code>100</code>.</td><td>Inteiro</td></tr></tbody></table>

#### Exemplo de solicitação

Para começar a filtrar dados, você primeiro precisa identificar seus recursos específicos. O exemplo a seguir mostra como listar suas instâncias disponíveis de Datacenter Proxies (DC) e Headless Browser (HB).

**Exemplo de entrada**

```
GET /stats/v1/filters/instances?products[]=HB&products[]=DC&page=1&per_page=50
Authorization: Bearer {YOUR_API_KEY}
```

**Exemplo de saída**

```json
{
  "data": [
    {
      "uuid": "my-hb-instance-uuid",
      "name": "my-hb-instance",
      "status": "enabled",
      "product": "HB"
    },
    {
      "uuid": "my-dc-instance-uuid",
      "name": "my-dc-instance",
      "status": "disabled",
      "product": "DC"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 50,
      "total_items": 2,
      "total_pages": 1
    }
  }
}
```

#### Campos de resposta

<table><thead><tr><th width="166">Campo</th><th width="268.0481770833333">Descrição</th><th>Tipo</th></tr></thead><tbody><tr><td><code>uuid</code></td><td>Identificador exclusivo da instância.</td><td>Cadeia de caracteres (UUID)</td></tr><tr><td><code>name</code></td><td>Nome da instância conforme configurado no dashboard.</td><td>Cadeia de caracteres</td></tr><tr><td><code>status</code></td><td>Status da instância do produto (por exemplo, <code>enabled</code> ou <code>disabled</code>).</td><td>Cadeia de caracteres</td></tr><tr><td><code>product</code></td><td>Identificador do produto (por exemplo, <code>HB</code> (Headless Browser), <code>DC</code> (Datacenter Proxies), etc.).</td><td>Cadeia de caracteres</td></tr><tr><td><code>página</code></td><td>Número da página atual.</td><td>Inteiro</td></tr><tr><td><code>por_page</code></td><td>Número de resultados nesta página.</td><td>Inteiro</td></tr><tr><td><code>total_items</code></td><td>Total de registros correspondentes em todas as páginas.</td><td>Inteiro</td></tr><tr><td><code>total_pages</code></td><td>Número total de páginas. Sempre pelo menos <code>1</code>, mesmo quando não há resultados.</td><td>Inteiro</td></tr></tbody></table>

### Estatísticas de uso

```
GET /stats/v1/usage
```

{% hint style="warning" %}
**Importante:** O intervalo máximo de datas para uma única solicitação (a diferença entre `date_to` e `date_from`) é de **31 dias**. Para recuperar dados de uso por um período maior, faça suas consultas em lotes de 31 dias.
{% endhint %}

#### Parâmetros de consulta

<table><thead><tr><th width="166">Parâmetro</th><th width="268.0481770833333">Descrição</th><th>Tipo</th></tr></thead><tbody><tr><td><mark style="background-color:green;"><code>product</code></mark></td><td>Identificador do produto (por exemplo, <code>HB</code> (Headless Browser), <code>DC</code> (Datacenter Proxies), etc.)</td><td>Cadeia de caracteres</td></tr><tr><td><mark style="background-color:green;"><code>date_to</code></mark></td><td>Data inicial, inclusiva (por exemplo, UTC <code>YYYY-MM-DDTHH:mm:ssZ</code> ou com fuso horário <code>YYYY-MM-DDTHH:mm:ss+02:00</code>).</td><td>Data (ISO 8601)</td></tr><tr><td><mark style="background-color:green;"><code>date_from</code></mark></td><td>Data final, inclusiva. Mesmo formato que <code>date_to</code>.</td><td>Data (ISO 8601)</td></tr><tr><td><mark style="background-color:green;"><code>group_by</code></mark></td><td>Opções de agrupamento dos resultados. Valores aceitos: <code>DAY</code>, <code>TARGET</code>, <code>INSTANCE</code>. Vários valores podem ser combinados. A ordem dos valores determina a ordem do agrupamento dos dados.</td><td>Vetor de strings</td></tr><tr><td><code>instances[]</code></td><td>Filtre os resultados para instâncias específicas. Aceita vários UUIDs obtidos de <code>GET /stats/v1/filters/instances</code>. UUIDs inválidos ou não reconhecidos são ignorados.</td><td>UUID (Vetor de strings)</td></tr><tr><td><code>página</code></td><td>Número da página. Padrão: <code>1</code>.</td><td>Inteiro</td></tr><tr><td><code>por_page</code></td><td>Resultados por página. Padrão: <code>100</code>. Máximo: <code>100</code>.</td><td>Inteiro</td></tr></tbody></table>

\- parâmetro obrigatório

#### Exemplos de solicitações

**1. Agrupar por TARGET**

O exemplo a seguir mostra como recuperar métricas de uso do Headless Browser (`HB`) agrupando os resultados por alvo, para ver a contagem total de solicitações e o volume de tráfego de cada alvo dentro do intervalo de datas selecionado.

**Exemplo de entrada**

```
GET /stats/v1/usage?product=HB&date_from=2025-11-01T00:00:00Z&date_to=2025-11-30T23:59:59Z&group_by[]=TARGET
Authorization: Bearer {YOUR_API_KEY}
```

**Exemplo de saída**

```json
{
  "data": [
    {"grouped_by": ["some.target.A"], "requests": 10, "traffic_bytes": 100},
    {"grouped_by": ["some.target.B"], "requests": 10, "traffic_bytes": 100}
  ],
  "totals": {
    "requests": 20,
    "traffic_bytes": 200
  },
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 50,
      "total_items": 100,
      "total_pages": 2
    },
    "grouping": ["TARGET"]
  }
```

**2. Agrupar por DAY + TARGET**

Este exemplo mostra como detalhar o uso do Headless Browser (`HB`) por `Dia` e `Alvo` para ver exatamente quanto tráfego cada alvo consumiu em base diária.

**Exemplo de entrada**

```
GET /stats/v1/usage?product=HB&date_from=2025-11-01T00:00:00Z&date_to=2025-11-30T23:59:59Z&group_by[]=DAY&group_by[]=TARGET
Authorization: Bearer {YOUR_API_KEY}
```

**Exemplo de saída**

```json

  "data": [
    {"grouped_by": ["2025-11-01", "some.target.A"], "requests": 10, "traffic_bytes": 100},
    {"grouped_by": ["2025-11-01", "some.target.B"], "requests": 10, "traffic_bytes": 100},
    {"grouped_by": ["2025-11-02", "some.target.A"], "requests": 10, "traffic_bytes": 100},
    {"grouped_by": ["2025-11-02", "some.target.B"], "requests": 10, "traffic_bytes": 100}
  ],
  "totals": {
    "requests": 40,
    "traffic_bytes": 400
  },
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 50,
      "total_items": 200,
      "total_pages": 4
    },
    "grouping": ["DAY", "TARGET"]
  }
}
```

#### Campos de resposta

<table><thead><tr><th width="190">Campo</th><th width="344.0481770833333">Descrição</th><th>Tipo</th></tr></thead><tbody><tr><td><code>grouped_by</code></td><td>Opções de agrupamento na mesma ordem dos <code>group_by</code> parâmetros solicitados.</td><td>Vetor de strings</td></tr><tr><td><code>data.requests</code></td><td>Contagem total de solicitações para a combinação de período/dimensão agrupada.</td><td>Inteiro</td></tr><tr><td><code>data.traffic_bytes</code></td><td>Tráfego total em bytes para a combinação de período/dimensão agrupada.</td><td>Inteiro</td></tr><tr><td><code>totals</code></td><td>Valores totais agregados para o período selecionado.</td><td>Objeto</td></tr><tr><td><code>totals.requests</code></td><td>Contagem total de solicitações em todo o período selecionado.</td><td>Inteiro</td></tr><tr><td><code>totals.traffic_bytes</code></td><td>Tráfego total em bytes em todo o período selecionado.</td><td>Inteiro</td></tr><tr><td><code>página</code></td><td>Número da página atual.</td><td>Inteiro</td></tr><tr><td><code>por_page</code></td><td>Número de resultados nesta página.</td><td>Inteiro</td></tr><tr><td><code>total_items</code></td><td>Total de registros correspondentes em todas as páginas.</td><td>Inteiro</td></tr><tr><td><code>total_pages</code></td><td>Número total de páginas. Sempre pelo menos <code>1</code>, mesmo quando não há resultados.</td><td>Inteiro</td></tr><tr><td><code>meta.grouping</code></td><td>As opções de agrupamento ativas na ordem em que aparecem em <code>grouped_by</code>. Reflete o <code>group_by</code> parâmetro da solicitação.</td><td>Vetor de strings</td></tr></tbody></table>

## Limites de taxa

Para garantir estabilidade, limites de taxa da Dashboard API são aplicados por chave de API e por conta de cliente para todas as solicitações.

* `10` solicitações por chave de API
* `100` solicitações em todas as chaves de API de um cliente individual

## Tratamento de erros

Aqui estão alguns tipos comuns de erro que você pode encontrar ao usar a Dashboard API:

<table><thead><tr><th width="166">Código de erro</th><th width="268.0481770833333">Mensagem de erro</th><th>Descrição</th></tr></thead><tbody><tr><td><code>400</code></td><td>Requisição inválida</td><td>A solicitação não pôde ser entendida. Verifique se a solicitação está formatada corretamente.</td></tr><tr><td><code>401</code></td><td>Solicitação inválida</td><td>O usuário inseriu uma chave de API inválida.</td></tr><tr><td><code>403</code></td><td>Proibido</td><td>Acesso negado: chave de API ausente. Entre em contato com o suporte ou com seu gerente de conta.</td></tr><tr><td><code>429</code></td><td>Muitas solicitações</td><td>O usuário atingiu o limite de threads/sessões simultâneas.</td></tr><tr><td><code>500</code></td><td>Erro interno do servidor</td><td>Tivemos um problema inesperado com o servidor. Tente novamente mais tarde.</td></tr></tbody></table>

Para dúvidas, problemas de acesso ou suporte de integração, entre em contato com [**support@oxylabs.io**](mailto:support@oxylabs.io) ou seu gerente de conta. Ao relatar um problema, inclua:

* O endpoint e os parâmetros de consulta usados
* O código de status HTTP retornado
* O corpo completo da resposta (remova sua chave de API antes de compartilhar)
* Timestamps das solicitações com falha (UTC preferencial)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.oxylabs.io/documentation/pt-br/painel/dashboard-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.