---
name: "Analytics"
last_updated: 2026-07-09T23:50:15Z
type: feature
api_base_url: "https://apis.roblox.com"
endpoints: 4
auth: [api-key, oauth2, cookie]
description: "Query analytics data for your experiences programmatically"
---

# Analytics

Query analytics data for your experiences programmatically. See the [Analytics guide](https://create.roblox.com/docs/cloud/guides/analytics) for Open Cloud setup and usage.

**Base URL:** `https://apis.roblox.com`

    ## Authentication

    Each endpoint requires one of the following authentication methods:

    - **API Key**: Pass your key in the `x-api-key` HTTP header. Create keys at [Creator Dashboard](https://create.roblox.com/dashboard/credentials).
- **OAuth 2.0**: Use Bearer token in the `Authorization` header. Authorization URL: `https://apis.roblox.com/oauth/v1/authorize`, Token URL: `https://apis.roblox.com/oauth/v1/token`
- **Cookie** *(not recommended)*: `.ROBLOSECURITY` cookie. Do not use in production.

    ```
    # API Key example
    curl -H "x-api-key: YOUR_API_KEY" https://apis.roblox.com/...

    # OAuth 2.0 example
    curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" https://apis.roblox.com/...
    ```

## Endpoints

### POST `/analytics-query-api/v1/universes/{universeId}/dimension-values` [BETA]

Queries dimension values for a universe.

See the <a href="https://create.roblox.com/docs/cloud/guides/analytics">Analytics guide</a> for more information.

**Auth:** API Key (`x-api-key` header)

**Scopes:** `universe.analytics:read`

**Parameters:**

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `universeId` | path | `integer` | Yes | The universe ID to query dimension values for. |

**Request Body:** `application/json` — Type: `DimensionValuesRequest`

See [DimensionValuesRequest](#dimensionvaluesrequest) in Models.

**Request example:**
```json
{
  "metric": "string",
  "dimensions": [
    "string"
  ],
  "startTime": "2024-01-01T00:00:00Z",
  "endTime": "2024-01-01T00:00:00Z",
  "filter": [
    {
      "dimension": "...",
      "values": "...",
      "operation": "..."
    }
  ],
  "granularity": "OneMinute"
}
```

**Responses:**

- `200`: OK → `DimensionValuesOperationResult`
- `202`: Accepted → `OperationPending`
- `400`: Bad Request → `OperationError`
- `403`: Forbidden → `OperationError`
- `429`: Too Many Requests → `OperationError`
- `500`: Internal Server Error → `OperationError`
- `503`: Service Unavailable → `OperationError`
- `504`: Gateway Timeout → `OperationError`

**Response fields** (`DimensionValuesOperationResult`)

See [DimensionValuesOperationResult](#dimensionvaluesoperationresult) in Models.

**Response example:**
```json
{
  "path": "string",
  "done": false,
  "response": {
    "values": [
      "..."
    ]
  },
  "metadata": {
    "createdTime": "2024-01-01T00:00:00Z"
  }
}
```

**Error handling:** `429`: Retry with exponential backoff (start at 1s). `403`: Verify your API key has the required scopes listed above. 

**Rate Limits:** perApiKeyOwner: 30/minute

**Example:**
```bash
curl -X POST -H "x-api-key: $ROBLOX_API_KEY" \
  "https://apis.roblox.com/analytics-query-api/v1/universes/{UNIVERSEID}/dimension-values" \
  -H "Content-Type: application/json" \
  -d '{
  "metric": "string",
  "dimensions": [
    "string"
  ],
  "startTime": "2024-01-01T00:00:00Z",
  "endTime": "2024-01-01T00:00:00Z",
  "filter": [
    {
      "dimension": "...",
      "values": "...",
      "operation": "..."
    }
  ],
  "granularity": "OneMinute"
}'
```

### POST `/analytics-query-api/v1/universes/{universeId}/metrics` [BETA]

Queries time series metric data for a universe.

See the <a href="https://create.roblox.com/docs/cloud/guides/analytics">Analytics guide</a> for more information.

**Auth:** API Key (`x-api-key` header)

**Scopes:** `universe.analytics:read`

**Parameters:**

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `universeId` | path | `integer` | Yes | The universe ID to query metrics for. |

**Request Body:** `application/json` — Type: `QueryRequest`

See [QueryRequest](#queryrequest) in Models.

**Request example:**
```json
{
  "metric": "string",
  "granularity": "OneMinute",
  "startTime": "2024-01-01T00:00:00Z",
  "endTime": "2024-01-01T00:00:00Z",
  "breakdown": [
    "string"
  ],
  "filter": [
    {
      "dimension": "...",
      "values": "...",
      "operation": "..."
    }
  ]
}
```

**Responses:**

- `200`: OK → `QueryOperationResult`
- `202`: Accepted → `OperationPending`
- `400`: Bad Request → `OperationError`
- `403`: Forbidden → `OperationError`
- `429`: Too Many Requests → `OperationError`
- `500`: Internal Server Error → `OperationError`
- `503`: Service Unavailable → `OperationError`
- `504`: Gateway Timeout → `OperationError`

**Response fields** (`QueryOperationResult`)

See [QueryOperationResult](#queryoperationresult) in Models.

**Response example:**
```json
{
  "path": "string",
  "done": false,
  "response": {
    "values": [
      "..."
    ]
  },
  "metadata": {
    "createdTime": "2024-01-01T00:00:00Z"
  }
}
```

**Error handling:** `429`: Retry with exponential backoff (start at 1s). `403`: Verify your API key has the required scopes listed above. 

**Rate Limits:** perApiKeyOwner: 30/minute

**Example:**
```bash
curl -X POST -H "x-api-key: $ROBLOX_API_KEY" \
  "https://apis.roblox.com/analytics-query-api/v1/universes/{UNIVERSEID}/metrics" \
  -H "Content-Type: application/json" \
  -d '{
  "metric": "string",
  "granularity": "OneMinute",
  "startTime": "2024-01-01T00:00:00Z",
  "endTime": "2024-01-01T00:00:00Z",
  "breakdown": [
    "string"
  ],
  "filter": [
    {
      "dimension": "...",
      "values": "...",
      "operation": "..."
    }
  ]
}'
```

### GET `/analytics-query-api/v1/universes/{universeId}/operations/dimension-values/{operationId}` [BETA]

Retrieves the result of a long-running dimension values operation.

See the <a href="https://create.roblox.com/docs/cloud/guides/analytics">Analytics guide</a> for more information.

**Auth:** API Key (`x-api-key` header)

**Scopes:** `universe.analytics:read`

**Parameters:**

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `universeId` | path | `integer` | Yes | The universe ID the operation belongs to. |
| `operationId` | path | `string` | Yes | The operation id returned from a prior dimension values request. |

**Responses:**

- `200`: OK → `DimensionValuesOperationResult`
- `202`: Accepted → `OperationPending`
- `400`: Bad Request → `OperationError`
- `404`: Not Found → `OperationError`
- `429`: Too Many Requests → `OperationError`
- `500`: Internal Server Error → `OperationError`
- `503`: Service Unavailable → `OperationError`
- `504`: Gateway Timeout → `OperationError`

**Response fields** (`DimensionValuesOperationResult`)

See [DimensionValuesOperationResult](#dimensionvaluesoperationresult) in Models.

**Response example:**
```json
{
  "path": "string",
  "done": false,
  "response": {
    "values": [
      "..."
    ]
  },
  "metadata": {
    "createdTime": "2024-01-01T00:00:00Z"
  }
}
```

**Error handling:** `429`: Retry with exponential backoff (start at 1s). 

**Rate Limits:** perApiKeyOwner: 3000/minute

**Example:**
```bash
curl -H "x-api-key: $ROBLOX_API_KEY" \
  "https://apis.roblox.com/analytics-query-api/v1/universes/{UNIVERSEID}/operations/dimension-values/{OPERATIONID}"
```

### GET `/analytics-query-api/v1/universes/{universeId}/operations/metrics/{operationId}` [BETA]

Retrieves the result of a long-running metrics query operation.

See the <a href="https://create.roblox.com/docs/cloud/guides/analytics">Analytics guide</a> for more information.

**Auth:** API Key (`x-api-key` header)

**Scopes:** `universe.analytics:read`

**Parameters:**

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `universeId` | path | `integer` | Yes | The universe ID the operation belongs to. |
| `operationId` | path | `string` | Yes | The operation id returned from a prior query request. |

**Responses:**

- `200`: OK → `QueryOperationResult`
- `202`: Accepted → `OperationPending`
- `400`: Bad Request → `OperationError`
- `404`: Not Found → `OperationError`
- `429`: Too Many Requests → `OperationError`
- `500`: Internal Server Error → `OperationError`
- `503`: Service Unavailable → `OperationError`
- `504`: Gateway Timeout → `OperationError`

**Response fields** (`QueryOperationResult`)

See [QueryOperationResult](#queryoperationresult) in Models.

**Response example:**
```json
{
  "path": "string",
  "done": false,
  "response": {
    "values": [
      "..."
    ]
  },
  "metadata": {
    "createdTime": "2024-01-01T00:00:00Z"
  }
}
```

**Error handling:** `429`: Retry with exponential backoff (start at 1s). 

**Rate Limits:** perApiKeyOwner: 3000/minute

**Example:**
```bash
curl -H "x-api-key: $ROBLOX_API_KEY" \
  "https://apis.roblox.com/analytics-query-api/v1/universes/{UNIVERSEID}/operations/metrics/{OPERATIONID}"
```

## Models

### DimensionValuesRequest

A request to query dimension values.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `metric` | `string` | Yes | The metric that provides context for resolving dimension namespaces. |
| `dimensions` | `string[]` | No | The dimensions to retrieve values for. Each entry is a single dimension name. |
| `startTime` | `string` | Yes | The inclusive start of the query time range. Any UTC offset is accepted; results are always bucketed in UTC. |
| `endTime` | `string` | Yes | The exclusive end of the query time range. Any UTC offset is accepted; results are always bucketed in UTC. |
| `filter` | `QueryFilter[]` | No | Filters to apply to the query. |
| `granularity` | `MetricGranularity` | No |  |
| `limit` | `integer` | No | The maximum number of values to return per dimension. |

### DimensionValuesOperationResult

A completed long-running dimension values operation with results.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `path` | `string` | No | The server-assigned resource path. |
| `done` | `boolean` | No | If false, the operation is still in progress. If true, the operation is completed. |
| `response` | `DimensionValuesResponse` | No |  |
| `metadata` | `OperationMetadata` | No |  |

### OperationPending

A long-running operation that is still in progress.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `path` | `string` | No | The server-assigned resource path. |
| `done` | `boolean` | No | If false, the operation is still in progress. If true, the operation is completed. |
| `metadata` | `OperationMetadata` | No |  |

### OperationError

A completed long-running operation that failed with an error.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `path` | `string` | No | The server-assigned resource path. |
| `done` | `boolean` | No | If false, the operation is still in progress. If true, the operation is completed. |
| `error` | `QueryError` | No |  |
| `metadata` | `OperationMetadata` | No |  |

### QueryRequest

A request to query time series metric data.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `metric` | `string` | Yes | The metric to query. |
| `granularity` | `MetricGranularity` | Yes |  |
| `startTime` | `string` | Yes | The inclusive start of the query time range. Any UTC offset is accepted; results are always bucketed in UTC. |
| `endTime` | `string` | Yes | The exclusive end of the query time range. Any UTC offset is accepted; results are always bucketed in UTC. |
| `breakdown` | `string[]` | No | The dimensions to group results by. Each entry is a single dimension name. |
| `filter` | `QueryFilter[]` | No | Filters to apply to the query. |
| `limit` | `integer` | No | The maximum number of breakdown series to return. |

### QueryOperationResult

A completed long-running query operation with results.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `path` | `string` | No | The server-assigned resource path. |
| `done` | `boolean` | No | If false, the operation is still in progress. If true, the operation is completed. |
| `response` | `QueryResponse` | No |  |
| `metadata` | `OperationMetadata` | No |  |