> ## Documentation Index > Fetch the complete documentation index at: https://docs.scaleo.io/llms.txt > Use this file to discover all available pages before exploring further. # Get statistics (GET) > Returns aggregated performance statistics with configurable breakdowns, columns, and filters. Supports grouping by date, offer, affiliate, country, device, etc. Date range parameters are interpreted in the authenticated user's timezone and automatically converted to UTC internally. ## OpenAPI ````yaml /brand.bundled.yaml get /api/v2/network/reports/statistics openapi: 3.1.0 info: title: Scaleo Brand API version: 0.1.1 summary: REST API for external integrations with the Scaleo affiliate platform. contact: name: Scaleo Support email: support@scaleo.io description: > The Scaleo Public API gives external systems the same capabilities as the dashboard, organised by user role — **Affiliate** and **Manager** — plus shared reference data. Use the sidebar guides to get started: | Guide | Covers | |---|---| | [Authentication](#tag/Authentication) | API keys, role scoping | | [Errors](#tag/Errors) | Response envelope, error codes | | [Pagination](#tag/Pagination) | List params, pagination headers | | [Versioning](#tag/Versioning) | Version prefix, compatibility | | [Conventions](#tag/Conventions) | Timestamps, IDs, currencies | ## Quick start Authenticate with your API key using the `X-API-Key` HTTP header (preferred): ``` GET https://your-domain.scaleo.io/api/v2/affiliate/profile X-API-Key: YOUR_KEY ``` The legacy `api-key` query parameter is still accepted but **deprecated** — see [Authentication](#tag/Authentication) for migration details. Every response uses a consistent JSON envelope: ```json { "message": "OK", "success": true, "info": { } } ``` `success` is `true` for 2xx responses and `false` for errors. See [Errors](#tag/Errors) for the full format and error codes. ## Roles | Role | Endpoint prefix | |---|---| | Manager | `/api/v2/network/...` | | Affiliate | `/api/v2/affiliate/...` | Each API key is bound to one role and cannot call endpoints of another role. servers: - url: https://{domain} description: Customer-specific deployment. variables: domain: default: operator.scaletrk.com description: Your Scaleo instance domain. security: - ApiKeyHeaderAuth: [] - ApiKeyAuth: [] tags: - name: Overview x-displayName: Overview description: > The Scaleo Public API exposes the same data and operations available in the web dashboard, organised by user role — **Affiliate** and **Manager** — plus a small set of shared resources. It is a REST API. All endpoints accept and return JSON, except for binary download endpoints (invoice PDFs, creative assets) which return raw file data. ## What you can do | Role | Capabilities | |---|---| | **Affiliates** | Offers, campaigns, payouts, click/conversion stats. | | **Managers** | Full administration: affiliates, offers, billing, tracking, reporting. | | **All roles** | Shared reference data — countries, categories, tags, tiers. | ## URL conventions | URL prefix | Role | |---|---| | `/api/v2/network/...` | Manager | | `/api/v2/affiliate/...` | Affiliate | `{id}` in paths is a numeric resource ID. All timestamps are ISO 8601 UTC. ## Where to start 1. Read **Authentication** in the sidebar and obtain an API key. 2. Read **Errors** to understand the response envelope. 3. Try `GET /api/v2/affiliate/profile` (or the equivalent for your role) to verify your key works. 4. Browse the role-scoped sections for the endpoints relevant to your integration. ## Support For integration support, contact your account manager or [support@scaleo.io](mailto:support@scaleo.io). - name: Authentication x-displayName: Authentication description: > All Public API requests are authenticated with an **API key**. Pass it in the `X-API-Key` HTTP request header — this is the **preferred** method: ``` GET https://your-domain.scaleo.io/api/v2/affiliate/profile X-API-Key: YOUR_KEY ``` The user account that owns the key must have `api_status` enabled. ## Deprecated: `api-key` query parameter The `api-key` URL query parameter is still accepted for backwards compatibility but is **deprecated** and will be removed in a future release: ``` GET https://your-domain.scaleo.io/api/v2/affiliate/profile?api-key=YOUR_KEY ``` :::warning Deprecated Migrate to the `X-API-Key` header. Support for the `api-key` query parameter will be removed approximately 6 months after this notice. ::: ## Role scoping Each API key is bound to a specific user role and **cannot** call endpoints outside that role: | Role | Endpoint prefix | |---|---| | Manager | `/api/v2/network/...` | | Affiliate | `/api/v2/affiliate/...` | Calling an endpoint with the wrong role's key returns `403 Forbidden`. ## Where to find your key * **Affiliate** — dashboard → **Profile → API**. * **Manager** — admin panel → **Users → Managers → {user} → API**. Keys can be regenerated at any time. Regeneration invalidates the previous key immediately. ## Security best practices :::tip The `X-API-Key` header keeps your API key out of URLs, request logs, and browser history — always prefer the header over the query parameter. ::: * Use **HTTPS** only — HTTP does not protect the key in transit. * If a key is leaked, rotate it from the dashboard immediately. * For server-to-server integrations, store keys in a secrets manager (e.g. AWS Secrets Manager, HashiCorp Vault) rather than in source control. - name: Errors x-displayName: Errors description: > Every Public API response uses the same JSON envelope regardless of whether the request succeeded: ```json { "message": "OK", "success": true, "info": { } } ``` | Field | Description | |---|---| | `message` · string | Human-readable result summary. | | `success` · boolean | `true` for 2xx, `false` for errors. | | `info` · object | Payload. Omitted when the response carries no data. | :::info The HTTP status code is the authoritative signal. `success` is a convenience for clients that cannot easily inspect HTTP status codes. ::: ## Standard error responses | HTTP status | When you see it | |---|---| | `400 Bad Request` | Invalid JSON, unknown parameter, or malformed request. | | `401 Unauthorized` | Missing or invalid API key (`X-API-Key` header or `api-key` query param), or `api_status` disabled. | | `403 Forbidden` | Key is valid but belongs to a different role. | | `404 Not Found` | Resource not found or not visible to this account. | | `422 Unprocessable Entity` | Validation failed — see `info.errors`. | | `500 Internal Server Error` | Server-side problem. Retry with backoff. | ## Validation errors (422) When validation fails the server returns `422`. Each key in `info.errors` is the failing field name; the value is an array of error strings: ```json { "message": "Validation error", "success": false, "info": { "errors": { "email": ["Email cannot be blank."], "currency": ["Currency must be a valid ISO code."] } } } ``` ## Retry guidance * `4xx` — client problem, fix the request before retrying. * `5xx` — transient server problem. Retry with exponential backoff (start 1 s, max 60 s, add 0–25% jitter). * `GET` and `PUT` on a known resource are always safe to retry. - name: Pagination x-displayName: Pagination description: > List endpoints support consistent query parameters for pagination, filtering, and sorting. ## Pagination parameters | Parameter | Default / Max | |---|---| | `page` · integer | default `1` | | `perPage` · integer | default `10`, max `1000` | :::info Pagination metadata is in response headers, not in the body. ::: Paginated responses carry metadata in **HTTP response headers**: | Header | Value | |---|---| | `X-Pagination-Current-Page` | Current page number | | `X-Pagination-Total-Count` | Total items across all pages | | `X-Pagination-Page-Count` | Total number of pages | | `X-Pagination-Per-Page` | Page size used for this request | Example response for a list endpoint: ```json { "message": "Affiliates List", "success": true, "info": { "affiliates": [] } } ``` With HTTP headers: ``` X-Pagination-Current-Page: 2 X-Pagination-Total-Count: 137 X-Pagination-Page-Count: 7 X-Pagination-Per-Page: 20 ``` ## Sorting | Parameter | Values | |---|---| | `sortField` | endpoint-specific field name | | `sortDirection` | `asc` (default) \| `desc` | ``` GET /api/v2/network/affiliates?sortField=created_at&sortDirection=desc&page=1&perPage=50 ``` ## Filtering | Parameter | Meaning | |---|---| | `field=value` | Exact match — e.g. `status=1` | | `field[]=v1&field[]=v2` | Match any value — e.g. `country[]=US&country[]=GB` | | `field_from` / `field_to` | Date or numeric range | | `q` | Full-text search | ## Date format All date and datetime filters accept ISO 8601. If no timezone is given, UTC is assumed. * Date only: `2026-01-20` * Datetime UTC: `2026-01-20T13:45:00Z` - name: Versioning x-displayName: Versioning description: > The Public API uses a path-based version prefix. | Version | Status | Prefix | |---|---|---| | **v2** | Stable, default | `/api/v2/...` | ## Compatibility policy * **Additive changes** (new fields, new endpoints) can appear without notice. Clients must tolerate unknown fields. * **Breaking changes** require a new major version, announced with a minimum 6-month deprecation window. * **Bug fixes** that alter response shape are treated as breaking. - name: Conventions x-displayName: Conventions description: > Conventions used across the entire Public API. ## Time and dates All timestamps are **ISO 8601 in UTC** unless explicitly noted: ``` 2026-01-20T13:45:00Z ``` Date-only fields (report ranges, billing periods) use `YYYY-MM-DD`. ## Identifiers * Resource IDs are positive integers. * Country IDs use **GeoNames** numeric IDs: `6252001` (US), `2635167` (GB). Full list: `GET /api/v2/common/lists/countries`. ## Currencies and monetary values * Currency codes follow **ISO 4217**: `USD`, `EUR`, `GBP`. * Monetary amounts have up to 4 decimal places: `12.5000`. Display rounding is the client's responsibility. ## Status values Many resources use a numeric `status` field: | Value | Meaning | |---|---| | `1` | Active | | `2` | Disabled / Inactive | | `3` | Pending review | | `4` | Rejected | Per-endpoint documentation lists the exact allowed values and any resource-specific additions. ## Booleans JSON booleans are always native `true` / `false`. Some legacy filters accept `1` / `0` as a fallback — prefer native booleans. ## Null and empty values * Optional fields absent from the record are returned as `null`, not omitted. * Empty collections are returned as `[]` (arrays) or `{}` (objects). * In `POST` / `PUT` bodies: sending `null` clears the field; omitting the key keeps the current value (unless noted in the endpoint description). ## Localisation Display strings (offer names, descriptions, creative captions) are returned in the network's configured primary language. There is no per-request locale override. - name: Affiliate / Profile x-displayName: Profile description: View and update affiliate account profile and basic info. - name: Affiliate / Dashboard x-displayName: Dashboard description: Aggregated network summary for the affiliate dashboard. - name: Affiliate / Campaigns x-displayName: Campaigns description: Manage tracking campaigns associated with offers. - name: Affiliate / Postbacks x-displayName: Postbacks description: Configure server-to-server postback URLs for conversion tracking. - name: Affiliate / Activity Log x-displayName: Activity Log description: Affiliate-scoped activity and audit log. - name: Affiliate / Billing / Balances x-displayName: Balances description: View affiliate balances and submit payout requests. - name: Affiliate / Billing / Invoices x-displayName: Invoices description: List affiliate invoices and download invoice PDFs. - name: Affiliate / Billing / Payment Methods x-displayName: Payment Methods description: Manage affiliate payment methods and supported currencies. - name: Affiliate / Billing / Preferences x-displayName: Billing Preferences description: View and update affiliate billing preferences. - name: Affiliate / Statistics / Reports x-displayName: Reports description: Aggregated statistics with flat and tree breakdowns. - name: Affiliate / Statistics / Clicks x-displayName: Clicks description: Click statistics and report options. - name: Affiliate / Statistics / Conversions x-displayName: Conversions description: Conversion statistics and report options. - name: Affiliate / Statistics / Players Operator x-displayName: Players (Operator) description: Export player data for operator integrations. - name: Affiliate / Statistics / Traders Broker x-displayName: Traders (Broker) description: Export trader data for broker integrations. - name: Manager / Dashboard x-displayName: Dashboard description: Top affiliates and top offers summaries for the network dashboard. - name: Manager / Activity Log x-displayName: Activity Log description: Network-wide activity and audit log. - name: Manager / Auth Tools x-displayName: Auth Tools description: Login link generation, 2FA login links, and password reset utilities. - name: Manager / Affiliates / Management x-displayName: Affiliates description: Create, list, view, and update affiliate accounts and filters. - name: Manager / Affiliates / Postbacks x-displayName: Affiliate Postbacks description: Manage postbacks at the affiliate level. - name: Manager / Affiliates / Promo Codes x-displayName: Promo Codes description: Manage affiliate promo codes individually or in bulk. - name: Manager / Campaigns x-displayName: Campaigns description: Manage tracking campaigns at the network level. - name: Manager / Billing x-displayName: Billing description: Network-level billing settings and payment methods. - name: Manager / Billing / Affiliate Billing x-displayName: Affiliate Billing description: Affiliate billing — balances, invoices, payment methods, preferences. - name: Manager / Billing / Commission Plans x-displayName: Commission Plans description: Create and assign commission plans to affiliates. - name: Manager / Statistics / Reports x-displayName: Reports description: Aggregated statistics — flat and tree breakdowns, columns config. - name: Manager / Statistics / Clicks x-displayName: Clicks description: Network-level click statistics. - name: Manager / Statistics / Conversions x-displayName: Conversions description: Network-level conversion statistics, including status changes. - name: Manager / Statistics / Logs x-displayName: Logs description: Raw click logs and inbound/outbound postback logs. - name: Manager / Tracking / Clicks x-displayName: Clicks description: Server-side click tracking — single and batch insert. - name: Manager / Tracking / Conversions x-displayName: Conversions description: Server-side conversion tracking and conversion lookups. - name: Manager / Tracking / Events x-displayName: Events description: Custom event updates. - name: Manager / Tracking / Promo Codes x-displayName: Promo Code Tracking description: Server-side promo-code tracking endpoints. - name: Manager / Statistics / Events x-displayName: Events description: >- Raw event-level data — registrations, deposits, withdrawals, bets, wins, and other industry-specific events. - name: Manager / Statistics / Players (Operator) x-displayName: Players (Operator) description: Network-level export of player data for operator integrations. - name: Manager / Statistics / Traders (Broker) x-displayName: Traders (Broker) description: Network-level export of trader data for broker integrations. - name: Common / Lists x-displayName: Reference Lists description: >- Static reference data — countries, categories, tags, tiers, traffic sources. paths: /api/v2/network/reports/statistics: get: tags: - Manager / Statistics / Reports summary: Get statistics (GET) description: >- Returns aggregated performance statistics with configurable breakdowns, columns, and filters. Supports grouping by date, offer, affiliate, country, device, etc. Date range parameters are interpreted in the authenticated user's timezone and automatically converted to UTC internally. operationId: getV2_networkReportsStatistics parameters: - name: rangeFrom in: query required: true description: Date range start. Supports `YYYY-MM-DD` and `YYYY-MM-DD HH:mm:ss`. schema: type: string - name: rangeTo in: query required: true description: Date range end. Supports `YYYY-MM-DD` and `YYYY-MM-DD HH:mm:ss`. schema: type: string - name: page in: query description: Page number. schema: type: integer default: 1 - name: perPage in: query description: Items per page. schema: type: integer default: 10 - name: sortField in: query description: Sort by column key. Default is `added_timestamp`. schema: type: string - name: sortDirection in: query description: Sort direction. schema: type: string enum: - asc - desc default: desc - name: columns in: query description: >- Comma-separated metric keys (e.g. clicks,cv_approved,cr,approved_payout). schema: type: string - name: breakdown in: query description: >- Primary grouping dimension (e.g. offer, affiliate, country, device, goal). schema: type: string - name: breakdowns in: query description: Additional grouping dimensions, comma-separated. schema: type: string - name: reportType in: query description: 'Report type: `general` (default), `igaming`, `operator`, `broker`.' schema: type: string enum: - general - igaming - operator - broker - name: currency in: query description: Convert monetary values to this currency. schema: type: string - name: originalCurrency in: query description: >- Return monetary values in the original currency without conversion. Pass `yes` to enable. schema: type: string enum: - 'yes' - 'no' - name: search in: query description: Search text. schema: type: string responses: '200': description: Aggregated statistics. content: application/json: schema: type: object properties: status: type: string example: success code: type: integer example: 200 name: type: string example: OK message: type: string info: type: object properties: timezone: type: string description: >- Timezone used to interpret date range parameters (e.g., "UTC", "America/New_York"). rows: type: object properties: rows: type: array description: >- Aggregated statistics rows per breakdown dimension. items: type: object properties: clicks: type: integer description: Total number of clicks. unique_clicks: type: integer description: >- Number of unique clicks (deduplicated by IP/device). invalid_clicks: type: integer description: >- Number of clicks flagged as invalid by the anti-fraud system. cv_approved: type: integer description: Number of approved conversions. cr: type: integer description: >- Conversion rate — ratio of approved conversions to total clicks. approved_payout: type: integer description: >- Total payout amount for approved conversions. cv_pending: type: integer description: Number of conversions in pending status. pr: type: integer description: >- Pending rate — ratio of pending conversions to total clicks. cv_rejected: type: integer description: Number of rejected conversions. rr: type: integer description: >- Rejection rate — ratio of rejected conversions to total clicks. antifraud_logic_score: type: integer description: >- Aggregated anti-fraud score for this row's traffic. ar: type: integer description: >- Approval rate — ratio of approved conversions to total conversions. totals: type: object description: >- Aggregate totals across all rows in the current result set. properties: clicks: type: integer description: Total number of clicks. unique_clicks: type: integer description: >- Number of unique clicks (deduplicated by IP/device). invalid_clicks: type: integer description: >- Number of clicks flagged as invalid by the anti-fraud system. cv_approved: type: integer description: Number of approved conversions. cr: type: integer description: >- Conversion rate — ratio of approved conversions to total clicks. approved_payout: type: integer description: Total payout amount for approved conversions. cv_pending: type: integer description: Number of conversions in pending status. pr: type: integer description: >- Pending rate — ratio of pending conversions to total clicks. cv_rejected: type: integer description: Number of rejected conversions. rr: type: integer description: >- Rejection rate — ratio of rejected conversions to total clicks. antifraud_logic_score: type: integer description: Aggregated anti-fraud score for all rows. ar: type: integer description: >- Approval rate — ratio of approved conversions to total conversions. '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' components: responses: BadRequest: description: >- Malformed request — invalid JSON, unknown query parameter, or other request-level problem. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: Request could not be parsed. success: false info: errors: {} Unauthorized: description: >- Missing or invalid API key (`X-API-Key` header or `api-key` query param), or the user has `api_status` disabled. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: API key is invalid or missing. success: false Forbidden: description: >- API key is valid but role-scoped — the endpoint is not available for this role. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: This endpoint is not available for your role. success: false NotFound: description: Resource does not exist or is not visible to the calling account. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: Resource not found. success: false InternalServerError: description: Unexpected server-side problem. Safe to retry with exponential backoff. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: An unexpected error occurred. success: false info: errors: {} schemas: ErrorResponse: type: object description: | Standard error envelope returned by all non-2xx responses. See the **Errors** guide for full details and retry guidance. required: - message - success properties: message: type: string description: Human-readable description of the error. success: type: boolean enum: - false description: Always `false` for error responses. info: type: - object - 'null' description: >- Additional error details. Present for 400 and 500 responses; absent for 401, 403, 404. properties: errors: type: object description: >- Map of field names to arrays of error messages (present on 400/500). additionalProperties: type: array items: type: string securitySchemes: ApiKeyHeaderAuth: type: apiKey in: header name: X-API-Key description: >- Preferred authentication method. Pass the API key in the `X-API-Key` HTTP request header. The user account must have `api_status` enabled. ApiKeyAuth: type: apiKey in: query name: api-key description: >- Deprecated. Pass the API key as the `api-key` query parameter. Supported for backwards compatibility — migrate to the `X-API-Key` header instead. ````