# Audience Performance Reports

> Create, manage, and run saved Audience Performance reports with the REST API.

Source: https://docs.oursprivacy.com/docs/platform-api/audience-conversion-reports

Use saved Audience Performance reports to keep a named conversion event, audience definition, attribution window, and optional date range together. Run a saved report with its stored dates or supply `from` and `to` to override them for one request.

## GET /rest/v1/audience-conversion-reports

List saved Audience Performance report configurations, most recently updated first. Requires API-key scope or current OAuth user permission: web-analytics:view

Request URL: `GET https://app.oursprivacy.com/rest/v1/audience-conversion-reports`

Authentication: apiKey or oauth2.

### Responses

- `200`: Saved Audience Performance reports
- `400`: Bad Request
- `401`: Unauthorized — missing, invalid, or expired API key or OAuth access token
- `403`: Forbidden — credential does not have the required current Ours permission
- `404`: Not Found
- `500`: Internal Server Error

#### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `entities` | object[] | Yes |  |
| `entities[].reportId` | string (uuid) | Yes |  |
| `entities[].name` | string | Yes |  |
| `entities[].eventName` | string | Yes |  |
| `entities[].valueProperty` | string | Yes |  |
| `entities[].attributionWindow` | string | Yes |  |
| `entities[].filters` | object[] | Yes |  |
| `entities[].filters[].dimension` | string | Yes | One of: `"browser"`, `"campaign"`, `"city"`, `"content"`, `"country"`, `"device"`, `"entry_page"`, `"exit_page"`, `"medium"`, `"os"`, `"page"`, `"referrer"`, `"region"`, `"source"`, `"term"`. |
| `entities[].filters[].operator` | string | Yes | One of: `"CONTAINS"`, `"IS"`, `"IS_NOT"`, `"NOT_CONTAINS"`. |
| `entities[].filters[].values` | string[] | Yes |  |
| `entities[].dateFrom` | string \| null | No |  |
| `entities[].dateTo` | string \| null | No |  |
| `entities[].createdAt` | string | Yes |  |
| `entities[].updatedAt` | string | Yes |  |
| `entities[].webSourceId` | string \| null (uuid) | No |  |
| `entities[].excludeBots` | boolean \| null | No |  |

Full schema: [OpenAPI specification](https://docs.oursprivacy.com/openapi-platform.json).

## POST /rest/v1/audience-conversion-reports

Save an Audience Performance report configuration. Returns the full report so callers can run or update it without another request. Requires API-key scope or current OAuth user permission: web-analytics:write

Request URL: `POST https://app.oursprivacy.com/rest/v1/audience-conversion-reports`

Authentication: apiKey or oauth2.

### Request body (`application/json`, required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes |  |
| `eventName` | string | Yes |  |
| `valueProperty` | string | Yes |  |
| `attributionWindow` | string | Yes |  |
| `filters` | object[] | No |  |
| `filters[].dimension` | string | Yes | One of: `"browser"`, `"campaign"`, `"city"`, `"content"`, `"country"`, `"device"`, `"entry_page"`, `"exit_page"`, `"medium"`, `"os"`, `"page"`, `"referrer"`, `"region"`, `"source"`, `"term"`. |
| `filters[].operator` | string | No | One of: `"CONTAINS"`, `"IS"`, `"IS_NOT"`, `"NOT_CONTAINS"`. |
| `filters[].value` | string | No |  |
| `filters[].values` | string[] | No |  |
| `dateFrom` | string \| null | No |  |
| `dateTo` | string \| null | No |  |
| `webSourceId` | string \| null (uuid) | No |  |
| `excludeBots` | boolean \| null | No |  |

### Responses

- `200`: Created Audience Performance report
- `400`: Bad Request
- `401`: Unauthorized — missing, invalid, or expired API key or OAuth access token
- `403`: Forbidden — credential does not have the required current Ours permission
- `404`: Not Found
- `409`: The saved Audience Performance report limit has been reached.
- `500`: Internal Server Error

#### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reportId` | string (uuid) | Yes |  |
| `name` | string | Yes |  |
| `eventName` | string | Yes |  |
| `valueProperty` | string | Yes |  |
| `attributionWindow` | string | Yes |  |
| `filters` | object[] | Yes |  |
| `filters[].dimension` | string | Yes | One of: `"browser"`, `"campaign"`, `"city"`, `"content"`, `"country"`, `"device"`, `"entry_page"`, `"exit_page"`, `"medium"`, `"os"`, `"page"`, `"referrer"`, `"region"`, `"source"`, `"term"`. |
| `filters[].operator` | string | Yes | One of: `"CONTAINS"`, `"IS"`, `"IS_NOT"`, `"NOT_CONTAINS"`. |
| `filters[].values` | string[] | Yes |  |
| `dateFrom` | string \| null | No |  |
| `dateTo` | string \| null | No |  |
| `createdAt` | string | Yes |  |
| `updatedAt` | string | Yes |  |
| `webSourceId` | string \| null (uuid) | No |  |
| `excludeBots` | boolean \| null | No |  |

Full schema: [OpenAPI specification](https://docs.oursprivacy.com/openapi-platform.json).

## GET /rest/v1/audience-conversion-reports/{id}

Fetch a saved Audience Performance report by id. Requires API-key scope or current OAuth user permission: web-analytics:view

Request URL: `GET https://app.oursprivacy.com/rest/v1/audience-conversion-reports/{id}`

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | Yes |  |

### Responses

- `200`: Saved Audience Performance report
- `400`: Bad Request
- `401`: Unauthorized — missing, invalid, or expired API key or OAuth access token
- `403`: Forbidden — credential does not have the required current Ours permission
- `404`: Audience Performance report not found.
- `500`: Internal Server Error

#### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reportId` | string (uuid) | Yes |  |
| `name` | string | Yes |  |
| `eventName` | string | Yes |  |
| `valueProperty` | string | Yes |  |
| `attributionWindow` | string | Yes |  |
| `filters` | object[] | Yes |  |
| `filters[].dimension` | string | Yes | One of: `"browser"`, `"campaign"`, `"city"`, `"content"`, `"country"`, `"device"`, `"entry_page"`, `"exit_page"`, `"medium"`, `"os"`, `"page"`, `"referrer"`, `"region"`, `"source"`, `"term"`. |
| `filters[].operator` | string | Yes | One of: `"CONTAINS"`, `"IS"`, `"IS_NOT"`, `"NOT_CONTAINS"`. |
| `filters[].values` | string[] | Yes |  |
| `dateFrom` | string \| null | No |  |
| `dateTo` | string \| null | No |  |
| `createdAt` | string | Yes |  |
| `updatedAt` | string | Yes |  |
| `webSourceId` | string \| null (uuid) | No |  |
| `excludeBots` | boolean \| null | No |  |

Full schema: [OpenAPI specification](https://docs.oursprivacy.com/openapi-platform.json).

## PATCH /rest/v1/audience-conversion-reports/{id}

Update a saved Audience Performance report. Omitted fields remain unchanged, `filters: []` clears all filters, and dates must be sent or cleared as a pair. Requires API-key scope or current OAuth user permission: web-analytics:write

Request URL: `PATCH https://app.oursprivacy.com/rest/v1/audience-conversion-reports/{id}`

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | Yes |  |

### Request body (`application/json`, required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | No |  |
| `eventName` | string | No |  |
| `valueProperty` | string | No |  |
| `attributionWindow` | string | No |  |
| `filters` | object[] | No |  |
| `filters[].dimension` | string | Yes | One of: `"browser"`, `"campaign"`, `"city"`, `"content"`, `"country"`, `"device"`, `"entry_page"`, `"exit_page"`, `"medium"`, `"os"`, `"page"`, `"referrer"`, `"region"`, `"source"`, `"term"`. |
| `filters[].operator` | string | No | One of: `"CONTAINS"`, `"IS"`, `"IS_NOT"`, `"NOT_CONTAINS"`. |
| `filters[].value` | string | No |  |
| `filters[].values` | string[] | No |  |
| `dateFrom` | string \| null | No |  |
| `dateTo` | string \| null | No |  |
| `webSourceId` | string \| null (uuid) | No |  |
| `excludeBots` | boolean \| null | No |  |

### Responses

- `200`: Updated Audience Performance report
- `400`: Bad Request
- `401`: Unauthorized — missing, invalid, or expired API key or OAuth access token
- `403`: Forbidden — credential does not have the required current Ours permission
- `404`: Audience Performance report not found.
- `500`: Internal Server Error

#### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reportId` | string (uuid) | Yes |  |
| `name` | string | Yes |  |
| `eventName` | string | Yes |  |
| `valueProperty` | string | Yes |  |
| `attributionWindow` | string | Yes |  |
| `filters` | object[] | Yes |  |
| `filters[].dimension` | string | Yes | One of: `"browser"`, `"campaign"`, `"city"`, `"content"`, `"country"`, `"device"`, `"entry_page"`, `"exit_page"`, `"medium"`, `"os"`, `"page"`, `"referrer"`, `"region"`, `"source"`, `"term"`. |
| `filters[].operator` | string | Yes | One of: `"CONTAINS"`, `"IS"`, `"IS_NOT"`, `"NOT_CONTAINS"`. |
| `filters[].values` | string[] | Yes |  |
| `dateFrom` | string \| null | No |  |
| `dateTo` | string \| null | No |  |
| `createdAt` | string | Yes |  |
| `updatedAt` | string | Yes |  |
| `webSourceId` | string \| null (uuid) | No |  |
| `excludeBots` | boolean \| null | No |  |

Full schema: [OpenAPI specification](https://docs.oursprivacy.com/openapi-platform.json).

## DELETE /rest/v1/audience-conversion-reports/{id}

Delete a saved Audience Performance report configuration. Requires API-key scope or current OAuth user permission: web-analytics:write

Request URL: `DELETE https://app.oursprivacy.com/rest/v1/audience-conversion-reports/{id}`

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | Yes |  |

### Responses

- `200`: Deleted Audience Performance report
- `400`: Bad Request
- `401`: Unauthorized — missing, invalid, or expired API key or OAuth access token
- `403`: Forbidden — credential does not have the required current Ours permission
- `404`: Audience Performance report not found.
- `500`: Internal Server Error

#### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | Yes |  |
| `deleted` | boolean | Yes | One of: `true`. |

Full schema: [OpenAPI specification](https://docs.oursprivacy.com/openapi-platform.json).

## GET /rest/v1/audience-conversion-reports/{id}/results

Run a saved Audience Performance report. `from` and `to` override the saved date range when provided together. Returns 400 when neither a saved range nor an override is available. Requires API-key scope or current OAuth user permission: web-analytics:view

Request URL: `GET https://app.oursprivacy.com/rest/v1/audience-conversion-reports/{id}/results`

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | Yes |  |
| `from` | query | string | No |  |
| `to` | query | string | No |  |

### Responses

- `200`: Audience Performance report results
- `400`: A complete date range is required.
- `401`: Unauthorized — missing, invalid, or expired API key or OAuth access token
- `403`: Forbidden — credential does not have the required current Ours permission
- `404`: Audience Performance report not found.
- `500`: Internal Server Error

#### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `summary` | object | Yes |  |
| `summary.audienceSize` | integer | Yes |  |
| `summary.conversions` | integer | Yes |  |
| `summary.totalValue` | number | Yes |  |
| `summary.converters` | integer | Yes |  |
| `summary.conversionRate` | number | Yes |  |
| `summary.avgValuePerConversion` | number | Yes |  |
| `summary.avgValuePerConvertingVisitor` | number | Yes |  |
| `previousSummary` | object \| null | No |  |
| `previousSummary.audienceSize` | integer | Yes |  |
| `previousSummary.conversions` | integer | Yes |  |
| `previousSummary.totalValue` | number | Yes |  |
| `previousSummary.converters` | integer | Yes |  |
| `previousSummary.conversionRate` | number | Yes |  |
| `previousSummary.avgValuePerConversion` | number | Yes |  |
| `previousSummary.avgValuePerConvertingVisitor` | number | Yes |  |
| `timeseries` | object[] | Yes |  |
| `timeseries[].date` | string | Yes |  |
| `timeseries[].conversions` | integer | Yes |  |
| `timeseries[].totalValue` | number | Yes |  |
| `breakdown` | object[] | Yes |  |
| `breakdown[].source` | string | Yes |  |
| `breakdown[].medium` | string | Yes |  |
| `breakdown[].campaign` | string | Yes |  |
| `breakdown[].conversions` | integer | Yes |  |
| `breakdown[].converters` | integer | Yes |  |
| `breakdown[].totalValue` | number | Yes |  |

Full schema: [OpenAPI specification](https://docs.oursprivacy.com/openapi-platform.json).