# Dashboard API

O **Dashboard API** 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:** O Dashboard API atualmente oferece suporte a **Datacenter Proxies (DC**) e **Headless Browser (HB)**. Você também pode acompanhar as estatísticas de uso de [**Residential Proxies**](/products/proxies/residential-proxies/public-api.md), [**Mobile Proxies**](/products/proxies/mobile-proxies/public-api.md), [**Web Unblocker**](/products/web-unblocker/usage-statistics.md), e [**Web Scraper API**](/products/web-scraper-api/usage-and-billing/usage-statistics.md) com solicitações simples de API.
{% endhint %}

Todas as solicitações de 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) . Após a solicitação, 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

O 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 produtos às quais sua conta tem autorização de acesso. Você pode usar os IDs retornados para filtrar 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>Filtrar por produto. Valores aceitos: <code>HB</code> (Headless 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>Integer</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>Integer</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 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**&#x20;

```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 único 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 (ex.: <code>enabled</code> ou <code>disabled</code>).</td><td>String</td></tr><tr><td><code>product</code></td><td>Identificador do produto (ex.: <code>HB</code> (Headless 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>Integer</td></tr><tr><td><code>per_page</code></td><td>Número de resultados nesta página.</td><td>Integer</td></tr><tr><td><code>total_items</code></td><td>Total de registros correspondentes em todas as páginas.</td><td>Integer</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>Integer</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 days**. Para recuperar dados de uso por um período mais longo, 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 (ex.: <code>HB</code> (Headless 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, inclusiva (ex.: UTC <code>YYYY-MM-DDTHH:mm:ssZ</code> ou com fuso horário explícito <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, inclusiva. Mesmo formato de <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>Array de strings</td></tr><tr><td><code>instances[]</code></td><td>Filtra 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>Integer</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>Integer</td></tr></tbody></table>

&#x20;     \- parâmetro obrigatório

#### Exemplos de solicitação

**1. Agrupar por TARGET**

O exemplo a seguir mostra como recuperar métricas de uso do Headless Browser (`HB`) agrupando 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**&#x20;

```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 `Target` 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**&#x20;

```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</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>Integer</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>Integer</td></tr><tr><td><code>totals</code></td><td>Valores totais agregados para o período selecionado.</td><td>Object</td></tr><tr><td><code>totals.requests</code></td><td>Contagem total de solicitações em todo o período selecionado.</td><td>Integer</td></tr><tr><td><code>totals.traffic_bytes</code></td><td>Tráfego total em bytes em todo o período selecionado.</td><td>Integer</td></tr><tr><td><code>page</code></td><td>Número da página atual.</td><td>Integer</td></tr><tr><td><code>per_page</code></td><td>Número de resultados nesta página.</td><td>Integer</td></tr><tr><td><code>total_items</code></td><td>Total de registros correspondentes em todas as páginas.</td><td>Integer</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>Integer</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 de solicitação.</td><td>Array de strings</td></tr></tbody></table>

## Limites de taxa

Para garantir estabilidade, os limites de taxa do 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 de erro comuns que você pode encontrar ao usar o 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>Bad request</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>Invalid request</td><td>O usuário inseriu uma chave de API inválida.</td></tr><tr><td><code>403</code></td><td>Forbidden</td><td>Acesso negado: chave de API ausente. Entre em contato com o suporte ou com o gerente da sua conta.</td></tr><tr><td><code>429</code></td><td>Too many requests</td><td>O usuário atingiu o limite de threads/sessões simultâneas.</td></tr><tr><td><code>500</code></td><td>Internal server error</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 com o gerente da sua 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 (oculte sua chave de API antes de compartilhar)
* Os timestamps das solicitações com falha (UTC preferencial)


---

# Agent Instructions: 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:

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

The question should be specific, self-contained, and written in natural language.
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.