> ## 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. # List events > Returns a paginated list of raw events (registrations, deposits, withdrawals, bets, wins, FTDs, trades, and other industry-specific event types). All parameters are sent as a JSON body (`Content-Type: application/json`). **Date range is required.** Both `rangeFrom` and `rangeTo` must be present. **Columns selection:** use the `columns` field to specify which fields to return as a comma-separated list. The `currency` field is always appended automatically. When `insights` is included, `device_type`, `device_os`, and `device_os_version` are also appended automatically. **Filtering:** two independent filter mechanisms are available: - `filters` (object) — named shorthand filters for common dimensions (affiliates, offers, event types, geo, devices, etc.) - `filter` (object) — structured condition filter using operators (`=`, `!=`, `>`, `>=`, `<`, `<=`, `IN`, `NOT IN`, `LIKE`, `AND`, `OR`, `NOT`, `empty`) Pagination metadata is returned in response headers (`X-Pagination-*`). ## OpenAPI ````yaml /brand.bundled.yaml post /api/v2/network/reports/events 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/events: post: tags: - Manager / Statistics / Events summary: List events description: > Returns a paginated list of raw events (registrations, deposits, withdrawals, bets, wins, FTDs, trades, and other industry-specific event types). All parameters are sent as a JSON body (`Content-Type: application/json`). **Date range is required.** Both `rangeFrom` and `rangeTo` must be present. **Columns selection:** use the `columns` field to specify which fields to return as a comma-separated list. The `currency` field is always appended automatically. When `insights` is included, `device_type`, `device_os`, and `device_os_version` are also appended automatically. **Filtering:** two independent filter mechanisms are available: - `filters` (object) — named shorthand filters for common dimensions (affiliates, offers, event types, geo, devices, etc.) - `filter` (object) — structured condition filter using operators (`=`, `!=`, `>`, `>=`, `<`, `<=`, `IN`, `NOT IN`, `LIKE`, `AND`, `OR`, `NOT`, `empty`) Pagination metadata is returned in response headers (`X-Pagination-*`). operationId: postV2_networkReportsEvents requestBody: required: true content: application/json: schema: type: object required: - rangeFrom - rangeTo properties: rangeFrom: type: string format: date description: Start of the date range (inclusive). Format `YYYY-MM-DD`. example: '2025-01-01' rangeTo: type: string format: date description: End of the date range (inclusive). Format `YYYY-MM-DD`. example: '2025-01-31' page: type: integer default: 1 description: Page number. perPage: type: integer default: 10 description: Items per page. sortField: type: string default: added_timestamp description: > Field to sort by. Accepts any valid ClickHouse column name. Common values: `added_timestamp`, `added_date`, `sale_amount`, `affiliate_id`, `offer_id`, `click_id`, `transaction_id`. example: added_timestamp sortDirection: type: string enum: - asc - desc default: desc description: Sort direction. search: type: string description: > Free-text search (minimum 3 characters). Matches across: transaction ID, affiliate ID, offer ID, goal ID, campaign ID, click ID, track ID, order ID, user ID, adv_param1–5, aff_click_id, sub_id1–5, aff_param1–5, IP address. Users with `general_see_leads_details` permission additionally search custom1–10. columns: type: string description: > Comma-separated list of column names to include in the response. `currency` is always appended automatically. When `insights` is present, `device_type`, `device_os`, and `device_os_version` are also appended automatically. example: transaction_id,event_type,sale_amount,affiliate,offer filters: type: object description: > Named shorthand filters. Each value is a comma-separated string of IDs (integers) unless noted otherwise. properties: affiliates: type: string description: Comma-separated affiliate IDs. example: 1,2,3 offers: type: string description: Comma-separated offer IDs. advertisers: type: string description: Comma-separated advertiser (brand) IDs. event_types: type: string description: > Comma-separated event type codes. Possible values: `reg`, `ftd`, `qftd`, `dep`, `fdep`, `wdr`, `bon`, `bet`, `win`, `trd`, `pft`, `bal`, `ver`, `chb`, `rak`, `adj`, `ngr`, `psf`, `ctf`, `tax`, `bng`, `ggr`, `brf`, `rev`, `spr`, `depatt`. example: dep,wdr event_ids: type: string description: Comma-separated event (transaction) IDs. clickIds: type: string description: Comma-separated click IDs. aff_click_ids: type: string description: Comma-separated affiliate click IDs. track_ids: type: string description: Comma-separated track IDs. orders_ids: type: string description: Comma-separated advertiser order IDs. users_ids: type: string description: >- Comma-separated user IDs (player/trader IDs on the brand side). smartlinks: type: string description: Comma-separated smartlink IDs. commission_plan_ids: type: string description: Comma-separated commission plan IDs. currencies: type: string description: Comma-separated currency codes. example: USD,EUR countries: type: string description: Comma-separated GEO country IDs. offers_goals: type: string description: Comma-separated goal IDs. goals_types: type: string description: Comma-separated goal type IDs. offers_categories: type: string description: Comma-separated offer category IDs. offers_tags: type: string description: Comma-separated offer tag IDs. offers_creatives: type: string description: Comma-separated creative IDs. offers_links: type: string description: Comma-separated landing page IDs. affiliates_managers: type: string description: >- Comma-separated affiliate manager IDs. Restricts results to affiliates managed by these managers. advertisers_managers: type: string description: >- Comma-separated advertiser manager IDs. Restricts results to advertisers managed by these managers. affiliates_tags: type: string description: Comma-separated affiliate tag IDs. affiliates_subids1: type: string description: Comma-separated sub ID 1 values. affiliates_subids2: type: string description: Comma-separated sub ID 2 values. affiliates_subids3: type: string description: Comma-separated sub ID 3 values. affiliates_subids4: type: string description: Comma-separated sub ID 4 values. affiliates_subids5: type: string description: Comma-separated sub ID 5 values. affiliates_params1: type: string description: Comma-separated affiliate param 1 values. affiliates_params2: type: string description: Comma-separated affiliate param 2 values. affiliates_params3: type: string description: Comma-separated affiliate param 3 values. affiliates_params4: type: string description: Comma-separated affiliate param 4 values. affiliates_params5: type: string description: Comma-separated affiliate param 5 values. advertisers_params1: type: string description: Comma-separated advertiser param 1 values. advertisers_params2: type: string description: Comma-separated advertiser param 2 values. advertisers_params3: type: string description: Comma-separated advertiser param 3 values. advertisers_params4: type: string description: Comma-separated advertiser param 4 values. advertisers_params5: type: string description: Comma-separated advertiser param 5 values. clicks_referrers: type: string description: Filter by click referer URL. deep_links: type: string description: Filter by deep link value. conversions_referrers: type: string description: Filter by conversion referer URL. ips: type: string description: Filter by IP address (IPv4 or IPv6). geo: type: string description: GEO filter value. promo_codes: type: string description: Comma-separated promo code values. devices_types: type: string description: Comma-separated device type IDs. devices_brands: type: string description: Comma-separated device brand IDs. devices_models: type: string description: Comma-separated device model IDs. devices_os: type: string description: Comma-separated operating system IDs. devices_os_version: type: string description: Comma-separated OS version strings. browsers: type: string description: Comma-separated browser IDs. browser_version: type: string description: Comma-separated browser version IDs. languages: type: string description: Comma-separated browser locale IDs. connections_types: type: string description: Comma-separated connection type IDs. mobile_operators: type: string description: Comma-separated mobile operator IDs. filter: type: object description: > Structured condition filter (ActiveDataFilter). Supports complex conditions with operators: `=`, `!=`, `>`, `>=`, `<`, `<=`, `IN`, `NOT IN`, `LIKE`, `empty`, and conjunctions `AND`, `OR`, `NOT`. Filterable attributes (map key → ClickHouse column): `event_ids` → transaction_id, `clickIds` → click_id, `event_types` → event_type, `affiliates` → affiliate_id, `affiliates_managers`, `affiliates_tags`, `aff_click_ids` → aff_click_id, `affiliates_subids1–5`, `affiliates_params1–5`, `clicks_referrers` → click_referer, `deep_links` → deep_link, `advertisers` → advertiser_id, `advertisers_managers`, `offers` → offer_id, `offers_categories`, `offers_tags`, `offers_goals` → goal_id, `goals_types` → goal_type, `currencies` → currency, `offers_creatives` → creative_id, `smartlinks` → smartlink_id, `offers_links` → link_id, `promo_codes` → promo_code, `track_ids` → track_id, `orders_ids` → order_id, `users_ids` → user_id, `advertisers_params1–5`, `conversions_referrers`, `geo`, `countries` → country_id, `devices_types` → device_id, `devices_brands` → brand_id, `devices_models` → model_id, `devices_os` → os_id, `devices_os_version` → os_version, `browsers` → browser_id, `languages` → browser_locale_id, `connections_types` → connection_type_id, `mobile_operators` → mobile_operator_id, `ips` → ipv6, `commission_plan_ids` → commission_plan_id, `traffic_source_ids` → traffic_source_id, `traffic_approach_ids` → traffic_approach_id, `campaign_ids` → campaign_id, `is_frozen`, `clickPeriod` → click_timestamp, `registrationPeriod` → reg_timestamp, `ftdPeriod` → ftd_timestamp. example: AND: - affiliates: IN: - 1 - 2 - 3 - sale_amount: '>=': 100 example: rangeFrom: '2025-01-01' rangeTo: '2025-01-31' page: 1 perPage: 25 sortField: added_timestamp sortDirection: desc columns: transaction_id,event_type,sale_amount,affiliate,offer,currency filters: event_types: dep,wdr affiliates: 1,2 responses: '200': description: Paginated list of events. headers: X-Pagination-Current-Page: description: Current page number. schema: type: integer X-Pagination-Total-Count: schema: type: integer description: Total number of items. X-Pagination-Page-Count: description: Total number of pages. schema: type: integer X-Pagination-Per-Page: schema: type: integer description: Items per page. content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: Events List info: type: array items: type: object properties: transaction_id: type: string description: Unique event (transaction) UUID. click_id: type: string description: Click ID that generated this event (FixedString 32). created_at: type: integer description: >- Event timestamp (Unix). Sourced from `added_timestamp`. event_type: description: > Event type details. `null` if the type code is not in the platform map. oneOf: - type: 'null' - type: object properties: id: type: string description: Event type code (e.g. `dep`, `reg`, `ftd`). key: type: string description: >- Human-readable key (e.g. `deposit`, `registration`). title: type: string description: Display title. qty: type: integer description: >- Quantity (for repeatable events such as deposits). sale_amount: type: number description: >- Sale/revenue amount attached to the event (Decimal 18,4). currency: type: string description: >- Currency code of the event. Always returned regardless of `columns`. example: USD affiliate: type: object properties: id: type: integer value: type: string description: Affiliate company name. advertiser: type: object properties: id: type: integer value: type: string description: Advertiser (brand) company name. offer: type: object properties: id: type: integer value: type: string commission_plan: type: object properties: id: type: integer value: type: string landing_page: type: object properties: id: type: integer value: type: string creative: type: object properties: id: type: integer value: type: string smartlink: type: object properties: id: type: integer value: type: string campaign: type: object description: Campaign associated with the event's click. properties: id: type: integer value: type: string description: Campaign name. hash: type: string description: Campaign hash identifier. product: type: string description: Product title. track_id: type: string aff_click_id: type: string description: Affiliate-side click ID. advertiser_order_id: type: string description: Order ID from the advertiser (brand) system. user_id: type: string description: Player / trader user ID on the brand system. deep_link: type: string referer_url: type: string description: Click referer URL. aff_sub_id1: type: string aff_sub_id2: type: string aff_sub_id3: type: string aff_sub_id4: type: string aff_sub_id5: type: string aff_param1: type: string aff_param2: type: string aff_param3: type: string aff_param4: type: string aff_param5: type: string adv_param1: type: string adv_param2: type: string adv_param3: type: string adv_param4: type: string adv_param5: type: string ip: type: string description: >- Client IP address. Masked if GDPR IP-hiding is enabled. geo: type: string description: Country / region / city derived from IP. device_type: type: object properties: id: type: integer value: type: string device_brand: type: string device_model: type: string device_os: type: string device_os_version: type: number description: OS version (Decimal 8,2). browser: type: string browser_version: type: string language: type: string description: Browser locale title. connection_type: type: string mobile_operator: type: string description: Mobile carrier name. risk: type: integer description: Risk flag (UInt8 — 0 or 1). traffic_source: type: object properties: id: type: integer value: type: string traffic_approach: type: object properties: id: type: integer value: type: string custom1: type: string custom2: type: string custom3: type: string custom4: type: string custom5: type: string custom6: type: string custom7: type: string custom8: type: string custom9: type: string custom10: type: string suspicious: description: > Anti-fraud suspicious flag. Always `null` for event records (the flag lives on the click, not the event itself). type: 'null' anti_fraud_logic_scope: description: > Anti-fraud logic scope label. Always `null` for event records. type: 'null' frozen: type: boolean description: >- Whether the event is frozen. Only present when the freeze feature is enabled on the platform. insights: type: object description: > Parsed device / OS / geo insight data. Returned only when `insights` is included in `columns`. When requested, `device_type`, `device_os`, and `device_os_version` are automatically appended to the column list. properties: country: type: string description: >- Geo string derived from IP (country / region / city). example: US / California / San Francisco device: description: Detected device type. `null` if unknown. oneOf: - type: 'null' - type: object properties: type: type: string description: Device type ID (string-cast integer). value: type: string description: >- Device type name (e.g. `Desktop`, `Mobile`). os: description: Detected operating system. `null` if unknown. oneOf: - type: 'null' - type: object properties: type: type: integer description: OS ID. value: type: string description: OS name (e.g. `Windows`, `iOS`). version: type: string description: OS version (string-cast Decimal). suspicious: description: >- Fraud signal from the associated click. `null` if the click is not flagged. oneOf: - type: 'null' - type: object properties: value: description: >- Raw suspicious flag value from the click. '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '422': $ref: '#/components/responses/ValidationError' '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 ValidationError: description: Request body validation failed. `info.errors` lists the failing fields. content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' example: message: Validation error success: false info: errors: email: - Email cannot be blank. currency: - Currency must be a valid ISO code. 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 ValidationErrorResponse: type: object description: > 422 Unprocessable Entity envelope returned when request body validation fails. `info.errors` is a map of field name → array of error strings. required: - message - success - info properties: message: type: string description: Short summary, typically "Validation error". success: type: boolean enum: - false info: type: object required: - errors properties: errors: type: object description: Map of failing field names to their error messages. additionalProperties: type: array items: type: string example: email: - Email cannot be blank. currency: - Currency must be a valid ISO code. 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. ````