> 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 Dashboard

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

O **API do Dashboard** permite que você **acesse as estatísticas de uso do seu 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:** A Dashboard API atualmente suporta **Datacenter Proxies (DC**) e **Agent Browser (HB)**. Você também pode acompanhar [**Residential Proxies**](https://developers.oxylabs.io/products/pt-br/proxies/residential-proxies/public-api.md), [**Mobile Proxies**](https://developers.oxylabs.io/products/pt-br/proxies/mobile-proxies/public-api.md), [**Web Unblocker**](https://developers.oxylabs.io/products/pt-br/web-unblocker/usage-statistics.md), e [**Web Scraper API**](https://developers.oxylabs.io/products/pt-br/web-scraper-api/usage-and-billing/usage-statistics.md) estatísticas de uso com solicitações simples de API.
{% endhint %}

Todas as solicitações da 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) . Depois de solicitada, a chave será gerada e fornecida diretamente para você em até um dia útil.
{% endhint %}

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

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

## Endpoints

A Dashboard API inclui endpoints para Descoberta de instâncias do produto e Estatísticas de uso. 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 de instâncias de 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 de uso agregadas 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> (Agent Browser), <code>DC</code> (Datacenter Proxies), <code>null</code> (todos os produtos).</td><td>Array de strings</td></tr><tr><td><code>page</code></td><td>Número da página. Padrão: <code>1</code>.</td><td>Inteiro</td></tr><tr><td><code>per_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 os dados, primeiro você precisa identificar seus recursos específicos. O exemplo a seguir mostra como listar suas instâncias disponíveis de Datacenter Proxies (DC) e Agent 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 da 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>String (UUID)</td></tr><tr><td><code>name</code></td><td>Nome da instância conforme configurado no dashboard.</td><td>String</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>String</td></tr><tr><td><code>product</code></td><td>Identificador do produto (por exemplo, <code>HB</code> (Agent Browser), <code>DC</code> (Datacenter Proxies), etc.).</td><td>String</td></tr><tr><td><code>page</code></td><td>Número da página atual.</td><td>Inteiro</td></tr><tr><td><code>per_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`) é **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> (Agent Browser), <code>DC</code> (Datacenter Proxies), etc.)</td><td>String</td></tr><tr><td><mark style="background-color:green;"><code>date_to</code></mark></td><td>Data de início, inclusive (por exemplo, UTC <code>YYYY-MM-DDTHH:mm:ssZ</code> ou com deslocamento de 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 de fim, inclusive. 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 de 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>Array 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 (Array de strings)</td></tr><tr><td><code>page</code></td><td>Número da página. Padrão: <code>1</code>.</td><td>Inteiro</td></tr><tr><td><code>per_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ção

**1. Agrupar por TARGET**

O exemplo a seguir mostra como recuperar métricas de uso para Agent Browser (`HB`) ao agrupar os resultados por target, para ver a contagem total de solicitações e o volume de tráfego de cada target 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 Agent Browser (`HB`) por `Dia` e `Alvo` para ver exatamente quanto tráfego cada target consumiu dia a dia.

**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 da 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 em que aparecem em <code>group_by</code> os parâmetros solicitados.</td><td>Array 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>page</code></td><td>Número da página atual.</td><td>Inteiro</td></tr><tr><td><code>per_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>. Corresponde ao <code>group_by</code> parâmetro da solicitação.</td><td>Array de strings</td></tr></tbody></table>

## Limites de taxa

Para garantir a estabilidade, os 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 à integração, entre em contato com [**support@oxylabs.io**](mailto:support@oxylabs.io) ou com 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 da API antes de compartilhar)
* Carimbos de data e hora 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
