Dashboard API

Programmatic access to Oxylabs proxy users for tracking usage statistics with the Dashboard API.

The Dashboard API allows you to access your product usage statistics programmatically and integrate the metrics into your internal systems. This allows automated reporting and real-time usage monitoring without using the Oxylabs dashboard on the web.

Note: Dashboard API currently supports Datacenter Proxies (DC) and Headless Browser (HB). You can also track Residential Proxies, Mobile Proxies, Web Unblocker, and Web Scraper API usage statistics with simple API requests.

All API requests flow through this base path:

https://api.oxylabs.io/

Authentication

Important: To get your Dashboard API key, please contact our Customer Support team. Once requested, the key will be generated and given to you directly within one business day.

You must include the key in the Authorization header of every request using the Bearer scheme.

Authorization: Bearer {YOUR_API_KEY}

Endpoints

Dashboard API includes endpoints for product Instance Discovery and Usage Statistics. All responses are delivered in JSON format.

Endpoint	Description
Instance discovery	The request returns a paginated list of product instances your account is authorized to access. You can use the returned IDs to filter results when calling other endpoints.
Usage statistics	The request returns aggregated usage statistics per product for the authenticated client's product instances.

Instance Discovery

GET /stats/v1/filters/instances

Query parameters

Parameter	Description	Type
products[]	Filter by product. Accepted values: HB (Headless Browser), DC (Datacenter Proxies), null (all products).	Array of strings
page	Page number. Default: 1.	Integer
per_page	Results per page. Default: 100. Maximum: 100.	Integer

Example request

To start filtering data, you first need to identify your specific resources. The following example shows how to list your available Datacenter Proxies (DC) and Headless Browser (HB) instances.

Input sample

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

Output sample

{
  "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
    }
  }
}

Response fields

Field	Description	Type
uuid	Unique identifier for the instance.	String (UUID)
name	Instance name as configured in the dashboard.	String
status	Product instance status (e.g., enabled or disabled).	String
product	Product identifier (e.g., HB (Headless Browser), DC (Datacenter Proxies), etc.).	String
page	Current page number.	Integer
per_page	Number of results on this page.	Integer
total_items	Total matching records across all pages.	Integer
total_pages	Total number of pages. Always at least 1, even when there are no results.	Integer

Usage Statistics

GET /stats/v1/usage

Important: The maximum date range for a single request (the difference between date_to and date_from) is 31 days. To retrieve usage data for a longer period, please perform your queries in 31-day batches.

Query parameters

Parameter	Description	Type
product	Product identifier (e.g., HB (Headless Browser), DC (Datacenter Proxies), etc.)	String
date_to	Start date, inclusive (e.g., UTC YYYY-MM-DDTHH:mm:ssZ or offset-aware YYYY-MM-DDTHH:mm:ss+02:00).	Date (ISO 8601)
date_from	End date, inclusive. Same format as date_to.	Date (ISO 8601)
group_by	Result grouping options. Accepted values: DAY, TARGET, INSTANCE. Multiple values can be combined. The order of values determines the order of data grouping.	Array of strings
instances[]	Filter results to specific instances. Accepts multiple UUIDs obtained from GET /stats/v1/filters/instances. Invalid or unrecognized UUIDs are ignored.	UUID (Array of strings)
page	Page number. Default: 1.	Integer
per_page	Results per page. Default: 100. Maximum: 100.	Integer

- mandatory parameter

Example requests

1. Group by TARGET

The following example shows how to retrieve usage metrics for Headless Browser (HB) by grouping results by target, to see the total request count and traffic volume for each target within the selected date range.

Input sample

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}

Output sample

{
  "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. Group by DAY + TARGET

This example shows how to break down Headless Browser (HB) usage by both Day and Target to see exactly how much traffic each target consumed on a day-by-day basis.

Input sample

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}

Output sample

  "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"]
  }
}

Response fields

Field	Description	Type
grouped_by	Grouping options in the same order as the requested group_by parameters.	Array of strings
data.requests	Total request count for the grouped period/dimension combination.	Integer
data.traffic_bytes	Total traffic in bytes for the grouped period/dimension combination.	Integer
totals	Total aggregated values for the selected period.	Object
totals.requests	Total request count across the entire selected period.	Integer
totals.traffic_bytes	Total traffic in bytes across the entire selected period.	Integer
page	Current page number.	Integer
per_page	Number of results on this page.	Integer
total_items	Total matching records across all pages.	Integer
total_pages	Total number of pages. Always at least 1, even when there are no results.	Integer
meta.grouping	The active grouping options in the order they appear in grouped_by. Mirrors the group_by request parameter.	Array of strings

Rate Limits

To ensure stability, Dashboard API rate limits are applied per API key and per client account for all requests.

• 10 requests per API key

• 100 requests across all API keys of an individual client

Error Handling

Here are some common error types that you can get while using the Dashboard API:

Error code	Error message	Description
400	Bad request	The request could not be understood. Please check if the request is formatted correctly.
401	Invalid request	User has entered an invalid API key.
403	Forbidden	Access denied: missing API key. Please contact support or your account manager.
429	Too many requests	User has reached the thread/concurrent session limit.
500	Internal server error	We had an unexpected problem with the server. Try again later.

For questions, access issues, or integration support, please contact [email protected] or your account manager. When reporting a problem, please include:

• The endpoint and query parameters used

• The HTTP status code returned

• The full response body (redact your API key before sharing)

• Timestamps of the failing requests (UTC preferred)