> ## Documentation Index > Fetch the complete documentation index at: https://documentation.qonversion.io/llms.txt > Use this file to discover all available pages before exploring further. # Get users overview chart data > Retrieve users overview analytics. User filters and segmentation, no product filters. ## OpenAPI ````yaml /api-reference/analytics-api.yaml get /{projectApiKey}/chart/users-overview openapi: 3.0.3 info: title: Qonversion Public Analytics API description: > Public API for accessing Qonversion analytics chart data and customer information. ## Quick Start 1. Find your **Project API Key** in the Qonversion dashboard. 2. Use it in the URL path of any analytics endpoint, for example: `https://api.qonversion.io/v1/analytics/{YOUR_PROJECT_API_KEY}/chart/proceeds`. 3. No additional authentication headers are required. ## Where to find your API Key 1. Sign in to the Qonversion dashboard at https://dash.qonversion.io/. 2. Open your project, then go to **Project Settings** in the left sidebar. 3. In the **Project Keys** section, copy the value labelled **API Key**. The **Project Key** field above it is the SDK key and will not authorize this API. The API Key is a 32-character alphanumeric string (for example, `JFPATc4VaaWYsfurml3qZ4zsmNw0VfWH`). It contains no fixed prefix. ## Authentication Authentication is done via the **Project API Key** in the URL path. This key both identifies your project and authorizes access to its analytics data. No `Authorization` header or query token is needed. **Sandbox mode is not supported by this API.** Project API Keys prefixed with `test_` are accepted, but the prefix is stripped and the request is processed as production. Use your production key. **Security:** Treat your Project API Key as a secret. Do not embed it in client-side or mobile-app code, and do not commit it to public repositories. ## Rate Limiting - **Limit:** 30 requests per minute per project (`Analytics` rate limit). - **Response:** HTTP 429 when the limit is exceeded. The 429 response carries `Retry-After: 60` so clients can honour the standard back-off header. - **Cache fallback:** If the gateway has a recent successful response cached for the same path + query, it is returned instead of 429 with header `X-Cache: HIT`. Caches expire after 5 minutes. - **Recommendation:** Honour `Retry-After` and implement exponential backoff in your client. ## Available Charts Four chart endpoints are exposed publicly: - **`proceeds`** - revenue and proceeds metrics. Supports all filters and segmentation. - **`users-overview`** - user acquisition and retention. Supports user filters and segmentation. Does NOT support product filters. - **`paid-subscriptions-movement`** - subscription transitions (new, renewed, churned). Supports common + product filters only. Does NOT support segmentation, `filter[user_id]`, or `filter[device_id]`. - **`active-subscriptions`** - currently active subscribers. Supports product filters and segmentation. Does NOT support `filter[user_id]` or `filter[device_id]`. ## Client Generation This OpenAPI specification is designed for generating type-safe clients. Tools you can use: - [openapi-generator](https://openapi-generator.tech/) - [swagger-codegen](https://swagger.io/tools/swagger-codegen/) ## Example Request ```bash curl "https://api.qonversion.io/v1/analytics/JFPATc4VaaWYsfurml3qZ4zsmNw0VfWH/chart/proceeds?from=1699000000&to=1701000000&unit=day&environment=1" ``` Replace the path segment with your own 32-character API Key. ## Response Format **Success (200):** ```json { "data": { "code": "proceeds", "from": 1699000000, "to": 1701000000, "unit": "day", "environment": 1, "currency": "USD", "series": [] } } ``` **Error (4xx/5xx):** ```json { "error": { "code": "validation_error", "message": "Unprocessable request params", "type": "request" }, "meta": { "reference": "https://documentation.qonversion.io/reference/handling-api-errors" } } ``` version: 1.0.0 contact: name: Qonversion API Support url: https://documentation.qonversion.io email: support@qonversion.io servers: - url: https://api.qonversion.io/v1/analytics description: Production server security: [] tags: - name: Analytics Charts description: Dedicated endpoints for each analytics chart type - name: Customers description: Endpoints for retrieving customer data and aggregated customer metrics paths: /{projectApiKey}/chart/users-overview: get: tags: - Analytics Charts summary: Get users overview chart data description: > Retrieve users overview analytics. User filters and segmentation, no product filters. operationId: getUsersOverviewChart parameters: - $ref: '#/components/parameters/ProjectApiKey' - $ref: '#/components/parameters/FromTimestamp' - $ref: '#/components/parameters/ToTimestamp' - $ref: '#/components/parameters/TimeUnit' - $ref: '#/components/parameters/Environment' - $ref: '#/components/parameters/MaxSeries' - $ref: '#/components/parameters/Segmentation' - $ref: '#/components/parameters/FilterTargetPlatform' - $ref: '#/components/parameters/FilterCountry' - $ref: '#/components/parameters/FilterLocale' - $ref: '#/components/parameters/FilterModel' - $ref: '#/components/parameters/FilterOsVersion' - $ref: '#/components/parameters/FilterSdkVersion' - $ref: '#/components/parameters/FilterQUserId' - $ref: '#/components/parameters/FilterUserId' - $ref: '#/components/parameters/FilterDeviceId' - $ref: '#/components/parameters/FilterMediaSourceName' - $ref: '#/components/parameters/FilterCampaignName' - $ref: '#/components/parameters/FilterAdSetName' - $ref: '#/components/parameters/FilterAdName' responses: '200': description: Successful response with chart data content: application/json: schema: $ref: '#/components/schemas/ChartResponse' '400': description: Bad request - invalid parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized - invalid or missing Project API Key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Too many requests - rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: parameters: ProjectApiKey: name: projectApiKey in: path required: true description: >- Project API Key for authentication and project identification. A 32-character alphanumeric string copied from Project Settings -> Project Keys -> API Key in https://dash.qonversion.io/. The key has no fixed prefix. schema: type: string minLength: 1 example: JFPATc4VaaWYsfurml3qZ4zsmNw0VfWH FromTimestamp: name: from in: query required: false description: Start of time range (Unix timestamp, seconds). schema: type: integer format: int64 ToTimestamp: name: to in: query required: false description: >- End of time range (Unix timestamp, seconds). Must be greater than `from`. schema: type: integer format: int64 TimeUnit: name: unit in: query required: false description: Time grouping unit. schema: type: string enum: - hour - day - week - month default: day Environment: name: environment in: query required: false description: >- Environment type (0=Sandbox, 1=Production). Sandbox keys are not supported by this API; production keys requesting environment=0 will return no data. schema: type: integer enum: - 0 - 1 default: 1 MaxSeries: name: max_series in: query required: false description: Maximum number of series to return. schema: type: integer minimum: 0 maximum: 500 default: 50 Segmentation: name: segmentation in: query required: false description: >- Group by dimension. Not all charts support every segmentation; passing an unsupported value returns 400 with an explanatory message. schema: type: string FilterTargetPlatform: name: filter[target_platform][] in: query required: false description: Filter by platforms. schema: type: array items: type: string enum: - iOS - Android - Stripe style: form explode: true FilterCountry: name: filter[country][] in: query required: false description: Filter by countries (ISO 3166-1 alpha-2). schema: type: array items: type: string pattern: ^[A-Z]{2}$ style: form explode: true FilterLocale: name: filter[locale][] in: query required: false description: Filter by locales. schema: type: array items: type: string style: form explode: true FilterModel: name: filter[model][] in: query required: false description: Filter by device models. schema: type: array items: type: string style: form explode: true FilterOsVersion: name: filter[os_version][] in: query required: false description: Filter by OS versions. schema: type: array items: type: string style: form explode: true FilterSdkVersion: name: filter[sdk_version][] in: query required: false description: Filter by SDK versions. schema: type: array items: type: string style: form explode: true FilterQUserId: name: filter[q_user_id] in: query required: false description: Filter by Qonversion user ID. schema: type: string FilterUserId: name: filter[user_id] in: query required: false description: Filter by custom user ID. schema: type: string FilterDeviceId: name: filter[device_id] in: query required: false description: Filter by device ID. schema: type: string FilterMediaSourceName: name: filter[media_source_name][] in: query required: false description: Filter by media source names. schema: type: array items: type: string style: form explode: true FilterCampaignName: name: filter[campaign_name][] in: query required: false description: Filter by campaign names. schema: type: array items: type: string style: form explode: true FilterAdSetName: name: filter[ad_set_name][] in: query required: false description: Filter by ad set names. schema: type: array items: type: string style: form explode: true FilterAdName: name: filter[ad_name][] in: query required: false description: Filter by ad names. schema: type: array items: type: string style: form explode: true schemas: ChartResponse: type: object required: - data properties: data: $ref: '#/components/schemas/ChartData' ErrorResponse: type: object required: - error properties: error: type: object required: - code - message - type properties: code: type: string description: Machine-readable error code. example: validation_error message: type: string description: Human-readable error message. example: Unprocessable request params type: type: string description: High-level error class. example: request meta: type: object nullable: true description: >- Optional metadata. May contain a `reference` URL pointing to documentation for the error code. additionalProperties: true example: reference: https://documentation.qonversion.io/reference/handling-api-errors ChartData: type: object required: - code - from - to - unit - environment - seriesRelation - maxSeries - totalType - measure - currency - series properties: code: type: string description: Chart type identifier (echoes request). example: proceeds from: type: integer format: int64 description: Start of time range (Unix timestamp). example: 1699000000 to: type: integer format: int64 description: End of time range (Unix timestamp). example: 1701000000 unit: type: string enum: - hour - day - week - month description: Time grouping unit echoed from the request. example: day environment: type: integer enum: - 0 - 1 description: Environment (0=Sandbox, 1=Production). example: 1 seriesRelation: type: string enum: - partsOfWhole - independent description: >- Relationship between series (`partsOfWhole` = sum to total, `independent` = separate). example: partsOfWhole maxSeries: type: integer description: Maximum series count. example: 50 totalType: type: string enum: - sum - wavg description: Total calculation type (sum or weighted average). example: sum measure: type: string enum: - usd - count - percent description: Measurement unit. example: usd currency: type: string description: >- Currency code for the chart (typically `USD` for monetary measures, empty string otherwise). example: USD horizontalLabelType: type: string nullable: true description: >- Optional label format hint for the horizontal axis. Present only when set by the chart executor. example: default segmentation: type: string nullable: true description: >- Segmentation dimension used. Omitted when no segmentation was applied. example: country summarySeries: $ref: '#/components/schemas/Series' nullable: true description: >- Summary series. Present only when the chart is segmented and a roll-up exists. series: type: array description: Data series array. items: $ref: '#/components/schemas/Series' Series: type: object required: - label - data properties: label: type: string description: Series name. example: After refunds total: type: number format: double nullable: true description: Total value for the period (rounded to 2 decimals). example: 380276.24 totalPrev: type: number format: double nullable: true description: Total value for the previous period (rounded to 2 decimals). example: 326882.25 totalWeight: type: number format: double nullable: true description: Weight for weighted-average calculations. totalPrevWeight: type: number format: double nullable: true description: Previous-period weight for weighted-average calculations. totalIgnoreInFinal: type: boolean nullable: true description: >- Whether to ignore this series in final calculations. Only present when set. data: type: array description: Array of data points. items: $ref: '#/components/schemas/DataPoint' DataPoint: type: object required: - start_time - value properties: start_time: type: integer format: int64 description: Period start time (Unix timestamp). example: 1699000000 value: type: number format: double description: Metric value (rounded to 2 decimals). example: 6163.49 ````