XAA Analytics API
Overview
XAA Analytics API allows partners to retrieve analytical data. To obtain analytical data, you must use endpoints in the following format:
- http
1POST https://analytics.xsolla.com/api/v1/calc/view-model/{name}
Note that the POST method is used, not GET.
See the Endpoints section below for the full list of available endpoints.
Authentication
Headers
| Header | Required | Description |
|---|---|---|
Content-Type | YES | Must be application/json. |
Project-ID | YES | The ID of the specific project to scope the results to. Results are returned only for this project. |
Authorization | YES | Basic authentication header. The value is the string Basic <token>, where <token> is the Base64-encoded string merchant_id:api_key (for example, Base64 of 12345:<api_key>). |
Authentication format: The Authorization header must use the exact format Basic <base64(merchant_id:api_key)>.
api_key is shown in Publisher Account only at the time of creation and must be stored securely on your side. You can create an API key in the following sections:
Common Request Format
The request body is a JSON object. Only date_range is required. All other top-level fields are optional and may be omitted independently. This format is shared by all endpoints described below.
date_range REQUIRED
Defines the date window for the underlying data, based on a chosen date field.
| Field | Type | Description |
|---|---|---|
dimension | string | The date field to filter on, for example created_date. The exact field available depends on the endpoint — see the endpoint’s “Date field to filter” value. |
start_date | string (YYYY-MM-DD) | Start of the date range, inclusive. |
end_date | string (YYYY-MM-DD) | End of the date range, inclusive. |
Example:
- json
1"date_range": {
2 "dimension": "created_date",
3 "start_date": "2026-01-01",
4 "end_date": "2026-01-31"
5}
dimension_filters OPTIONAL
An array of filter conditions applied to specific dimensions (string fields). Any number of filter objects can be included, and they are combined to narrow the result set.
| Field | Type | Description |
|---|---|---|
dimension | string | The name of the dimension to filter on, for example payment_status or country_iso. |
operator | string | The comparison operator. Possible values: =, !=, LIKE, NOT LIKE, ILIKE, REGEXP, IN, NOT IN |
value | array | The list of values to match against, used with the selected operator. |
Example:
- json
1"dimension_filters": [
2 {
3 "dimension": "payment_status",
4 "operator": "IN",
5 "value": ["done", "canceled"]
6 },
7 {
8 "dimension": "country_iso",
9 "operator": "NOT IN",
10 "value": ["DE", "GB"]
11 }
12]
In this example, results are limited to records where payment_status is either done or canceled, and country_iso is anything other than DE or GB.
metric_filters OPTIONAL
An array of filter conditions applied to specific metrics (number fields). Any number of filter objects can be included, and they are combined to narrow the result set.
| Field | Type | Description |
|---|---|---|
metric | string | The name of the metric to filter on, for example payments or conversion. |
operator | string | The comparison operator. Possible values: =, !=, >, <, >=, <=, BETWEEN |
value | number or array of number | The list of values to match against, used with the selected operator. |
Example:
- json
1"metric_filters": [
2 {
3 "metric": "payments",
4 "operator": ">=",
5 "value": 100
6 },
7 {
8 "metric": "conversion",
9 "operator": "BETWEEN",
10 "value": [0.8, 1]
11 }
12]
order OPTIONAL
An array specifying sort order for the results. If multiple sort fields are provided, they are typically applied in the order listed: primary sort first, then secondary sort, and so on.
| Field | Type | Description |
|---|---|---|
field | string | The field to sort by, for example payment_amount or sales_tax. |
direction | string | Sort direction: asc for ascending or desc for descending. |
Example:
- json
1"order": [
2 { "field": "payment_amount", "direction": "desc" },
3 { "field": "sales_tax", "direction": "asc" }
4]
pagination OPTIONAL
Controls how many records are returned and from which offset.
| Field | Type | Description |
|---|---|---|
limit | integer | Default value: 1000. Maximum number of records to return. |
offset | integer | Default value: 0. Number of records to skip before starting to return results. |
Example:
- json
1"pagination": {
2 "limit": 100,
3 "offset": 10
4}
table_output OPTIONAL
| Field | Type | Description |
|---|---|---|
table_output | boolean | Default value: false. If true, the result is returned as a table suitable for direct display or export. If false, the result is formatted for injection into visual diagrams or charts. |
table_output: true when the response will be consumed by reports, exports, or any workflow expecting rows and columns.Endpoints
Each endpoint below follows the same request format described in the Common Request Format section above. Only the endpoint URL, fields to filter, data freshness, and fields in the response differ between endpoints.
Sites data by country
Key website performance metrics by country.
Endpoint
- http
1POST https://analytics.xsolla.com/api/v1/calc/view-model/sites
Date field to filter
created_date
Fields to filter
| Field | Type | Description |
|---|---|---|
project_id | string | Project ID from Publisher Account |
site_id | string | Site ID from Publisher Account |
country_iso | string | ISO code of the country where the visit or payment originated |
visits | integer | Number of unique visits on the site |
payments | integer | Number of payments completed on the site |
conversion | float | Conversion from visits to payments. Values range from 0 to 1. |
Data freshness
The data is current as of “yesterday”. Data is updated once a day at 3:00 AM UTC.
Fields in the response
| Field | Type | Description |
|---|---|---|
country_iso | string | ISO code of the country where the visit or payment originated |
visits | integer | Number of unique visits on the site |
payments | integer | Number of payments completed on the site |
conversion | float | Conversion from visits to payments |
Full request example
- curl
1curl -X POST https://analytics.xsolla.com/api/v1/calc/view-model/sites \
2 -H 'Content-Type: application/json' \
3 -H 'Project-ID: <project_id>' \
4 -H 'Authorization: Basic <base64(merchant_id:api_key)>' \
5 -d '{
6 "date_range": {
7 "dimension": "created_date",
8 "start_date": "2026-01-01",
9 "end_date": "2026-01-31"
10 },
11 "dimension_filters": [
12 {
13 "dimension": "country_iso",
14 "operator": "NOT IN",
15 "value": ["US"]
16 }
17 ],
18 "metric_filters": [
19 {
20 "metric": "payments",
21 "operator": ">",
22 "value": 0
23 }
24 ],
25 "order": [
26 {
27 "field": "country_iso",
28 "direction": "asc"
29 }
30 ],
31 "pagination": {
32 "limit": 10,
33 "offset": 10
34 },
35 "table_output": true
36 }'
Response example
- json
1{
2 "table_output": {
3 "columns": [
4 "country_iso",
5 "visits",
6 "payments",
7 "conversion"
8 ],
9 "rows": [
10 [
11 "CA",
12 192,
13 1,
14 0.005208333333333333
15 ],
16 [
17 "ES",
18 123,
19 1,
20 0.008130081300813009
21 ],
22 [
23 "HR",
24 76,
25 1,
26 0.013157894736842105
27 ],
28 [
29 "KR",
30 186,
31 2,
32 0.010752688172043012
33 ]
34 ]
35 }
36}
Payments
Key payment metrics.
Endpoint
- http
1POST https://analytics.xsolla.com/api/v1/calc/view-model/payments
Date field to filter
created_date
Fields to filter
| Field | Type | Description |
|---|---|---|
project_id | string | Project ID from Publisher Account |
instance_id | string | Payment method ID from Publisher Account |
user_country_name | string | Name of the country where the payment was made |
gross_revenue | float | The sum of completed payments |
payments | integer | Number of completed payments |
average_payment | float | Average payment (gross_revenue/payments) |
Data freshness
The data is current as of “yesterday”. Data is updated once a day at 3:00 AM UTC.
Fields in the response
created_date, gross_revenue, payments, average_payment.
Full request example
- curl
1curl -X POST https://analytics.xsolla.com/api/v1/calc/view-model/payments \
2 -H 'Content-Type: application/json' \
3 -H 'Project-ID: <project_id>' \
4 -H 'Authorization: Basic <base64(merchant_id:api_key)>' \
5 -d '{
6 "date_range": {
7 "dimension": "created_date",
8 "start_date": "2026-08-01",
9 "end_date": "2026-08-05"
10 },
11 "dimension_filters": [
12 {
13 "dimension": "user_country_name",
14 "operator": "NOT IN",
15 "value": ["Bulgaria"]
16 }
17 ],
18 "metric_filters": [
19 {
20 "metric": "payments",
21 "operator": ">",
22 "value": 1
23 }
24 ],
25 "order": [
26 {
27 "field": "user_country_name",
28 "direction": "asc"
29 }
30 ],
31 "pagination": {
32 "limit": 10,
33 "offset": 10
34 },
35 "table_output": true
36 }'
Response example
- json
1{
2 "table_output": {
3 "columns": [
4 "created_date",
5 "gross_revenue",
6 "payments",
7 "average_payment"
8 ],
9 "rows": [
10 [
11 "2026-08-01",
12 140617.89040875435,
13 5854,
14 24.020821730227937
15 ],
16 [
17 "2026-08-02",
18 121855.88295841217,
19 5064,
20 24.063168040760697
21 ],
22 [
23 "2026-08-03",
24 109016.88689517975,
25 4625,
26 23.57121878814697
27 ],
28 [
29 "2026-08-04",
30 95804.32790827751,
31 4308,
32 22.238701928569526
33 ],
34 [
35 "2026-08-05",
36 86038.59026670456,
37 4058,
38 21.202215442756174
39 ]
40 ]
41 },
42 "currency_iso": "USD"
43}
Users
Key metrics for paying users.
Endpoint
- http
1POST https://analytics.xsolla.com/api/v1/calc/view-model/users
Date field to filter
created_date
Fields to filter
| Field | Type | Description |
|---|---|---|
project_id | string | Project ID from Publisher Account |
instance_id | string | Payment method ID from Publisher Account |
user_country_name | string | Name of the country where the payment was made |
user_country_iso | string | ISO code of the country where the payment was made |
gross_revenue | float | The sum of completed payments |
paying_users | integer | Number of unique users (V1 + project_id) with completed payments |
conversion | float | Conversion from total users to paying users. Values range from 0 to 1. |
arppu | float | Average revenue per paying user. (gross_revenue/paying_users) |
Data freshness
The data is current as of “yesterday”. Data is updated once a day at 3:00 AM UTC.
Fields in the response
created_date, gross_revenue, paying_users, conversion, arppu.
Full request example
- curl
1curl -X POST https://analytics.xsolla.com/api/v1/calc/view-model/users \
2 -H 'Content-Type: application/json' \
3 -H 'Project-ID: <project_id>' \
4 -H 'Authorization: Basic <base64(merchant_id:api_key)>' \
5 -d '{
6 "date_range": {
7 "dimension": "created_date",
8 "start_date": "2026-08-01",
9 "end_date": "2026-08-10"
10 },
11 "dimension_filters": [
12 {
13 "dimension": "user_country_name",
14 "operator": "NOT IN",
15 "value": ["Bulgaria"]
16 }
17 ],
18 "table_output": true
19 }'
Response example
- json
1{
2 "table_output": {
3 "columns": [
4 "created_date",
5 "gross_revenue",
6 "paying_users",
7 "conversion",
8 "arppu"
9 ],
10 "rows": [
11 [
12 "2026-08-01",
13 140927.00986981392,
14 3928,
15 0.9550206661804036,
16 35.877548337529
17 ],
18 [
19 "2026-08-02",
20 122114.79968571663,
21 3570,
22 0.940463645943098,
23 34.20582624249766
24 ],
25 [
26 "2026-08-03",
27 109302.27986955643,
28 3300,
29 0.9493670886075949,
30 33.12190299077467
31 ],
32 [
33 "2026-08-04",
34 95977.3898139,
35 3126,
36 0.9452676141517992,
37 30.70293979971209
38 ],
39 [
40 "2026-08-05",
41 86172.48967909813,
42 2886,
43 0.9509060955518945,
44 29.858797532605035
45 ],
46 [
47 "2026-08-06",
48 184684.84008288383,
49 3324,
50 0.9505290248784672,
51 55.56102288895422
52 ],
53 [
54 "2026-08-07",
55 174706.3094921112,
56 3254,
57 0.9478590154383921,
58 53.68970789554739
59 ],
60 [
61 "2026-08-08",
62 115240.05996775627,
63 3014,
64 0.9513888888888888,
65 38.23492367875125
66 ],
67 [
68 "2026-08-09",
69 99993.79971218109,
70 3075,
71 0.9467364532019704,
72 32.518308849489785
73 ],
74 [
75 "2026-08-10",
76 152139.73991513252,
77 3952,
78 0.9481765834932822,
79 38.49689775180479
80 ]
81 ]
82 },
83 "currency_iso": "USD"
84}
Encontrou um erro de texto ou digitação? Selecione o texto e pressione Ctrl+Enter.
