VTurb Analytics API

https://vturb.gitbook.io/analytics-api/pt
Admin
VTurb Analytics API provides a robust set of endpoints for tracking and analyzing video engagement,...
Tokens:51,251
Snippets:160
Trust Score:9.8
Update:4 months ago
Show doc for...
Tokens:
Raw
### Response Example for /sessions/stats_by_day

Source: https://vturb.gitbook.io/analytics-api/pt/release-notes

This JSON array shows the expected response format for daily session statistics. Each object represents a day and includes various metrics like views, starts, finishes, engagement, and conversions.

```json
[
  {
    "date_key": "2023-01-01",
    "total_viewed": 200,
    "total_viewed_device_uniq": 180,
    "total_viewed_session_uniq": 190,
    "total_started": 250,
    "total_started_session_uniq": 230,
    "total_started_device_uniq": 220,
    "total_finished": 150,
    "total_finished_session_uniq": 140,
    "total_finished_device_uniq": 130,
    "engagement_rate": 75.56,
    "total_clicked": 50,
    "total_clicked_device_uniq": 45,
    "total_clicked_session_uniq": 40,
    "total_over_pitch": 30,
    "total_under_pitch": 10,
    "over_pitch_rate": 75.0,
    "total_conversions": 10,
    "overall_conversion_rate": 2.56,
    "total_amount_usd": 1000,
    "total_amount_brl": 1000,
    "total_amount_eur": 1000,
    "play_rate": 2.56
  },
  {
    "date_key": "2023-01-02",
    "total_viewed": 180,
    "total_viewed_device_uniq": 160,
    "total_viewed_session_uniq": 170,
    "total_started": 220,
    "total_started_session_uniq": 210,
    "total_started_device_uniq": 200,
    "total_finished": 130,
    "total_finished_session_uniq": 120,
    "total_finished_device_uniq": 110,
    "engagement_rate": 72.3,
    "total_clicked": 40,
    "total_clicked_device_uniq": 35,
    "total_clicked_session_uniq": 30,
    "total_over_pitch": 25,
    "total_under_pitch": 8,
    "over_pitch_rate": 75.76,
    "total_conversions": 8,
    "overall_conversion_rate": 2.27,
    "total_amount_usd": 800,
    "total_amount_brl": 800,
    "total_amount_eur": 800,
    "play_rate": 2.27
  }
]
```

--------------------------------

### Player Search Examples

Source: https://vturb.gitbook.io/analytics-api/pt/release-notes

Examples demonstrating how to use the 'name' and 'name_match' parameters in the /players/list endpoint for case-insensitive player searches. Supported match types include 'contains', 'starts_with', 'ends_with', and 'exact'.

```http
GET /players/list?name=campaign_1
```

```http
GET /players/list?name=BF&name_match=starts_with
```

```http
GET /players/list?name=_v2&name_match=ends_with
```

```http
GET /players/list?name=[VSL]%20Black%20Friday&name_match=exact
```

--------------------------------

### Enhanced Players List Endpoint Response Example

Source: https://vturb.gitbook.io/analytics-api/pt/release-notes

Example response from the improved /players/list endpoint. Includes new fields like 'pitch_time' and 'duration' for each player.

```json
[
  {
    "id": "player1",
    "name": "Meu Player",
    "pitch_time": 0,
    "duration": 3600,
    "created_at": "2025-06-05T10:00:00Z"
  }
]
```

--------------------------------

### Leaderboard Response Example

Source: https://vturb.gitbook.io/analytics-api/pt/release-notes

Example response structure for the event leaderboard endpoint, showing player rankings and engagement metrics.

```json
[
  {
    "leaderboard_name": "leaderboard_10",
    "event": "finished",
    "leaderboards": [
      {
        "player_id": "player1",
        "total_plays": 100,
        "uniq_plays": 50,
        "uniq_device_plays": 25
      }
    ]
  }
]
```

--------------------------------

### Quota Usage Response Example

Source: https://vturb.gitbook.io/analytics-api/pt/release-notes

Example JSON response for the /quota/usage endpoint. It shows quota details for a 60-second interval, including query limits and read byte usage. The 'note' field in 'queries' indicates that a single API request might count as multiple queries.

```json
{
  "quotas": [
    {
      "interval_seconds": 60,
      "interval_starts_at": "2026-04-27T12:34:00Z",
      "interval_ends_at":   "2026-04-27T12:35:00Z",
      "queries":    { "used": 20, "limit": 60, "remaining": 40, "note": "a single API request may count as more than one query against this limit" },
      "read_bytes": { "used": 92535478, "limit": null, "remaining": null }
    }
  ]
}
```

--------------------------------

### Request Example for /sessions/stats_by_day

Source: https://vturb.gitbook.io/analytics-api/pt/release-notes

This JSON object demonstrates the structure for requesting daily session statistics. It includes parameters for player ID, date range, timezone, and video-specific settings.

```json
{
  "player_id": "65fb3c74ab21c70007b3e0dd",
  "start_date": "2023-01-01",
  "end_date": "2023-01-31",
  "timezone": "America/Sao_Paulo",
  "video_duration": 3600,
  "pitch_time": 30
}
```

--------------------------------

### New Endpoint: Session Stats Request Example

Source: https://vturb.gitbook.io/analytics-api/pt/release-notes

Example of a request payload for the new /sessions/stats endpoint. Use this to retrieve comprehensive session statistics for a specific player.

```json
{
  "player_id": "65fb3c74ab21c70007b3e0dd",
  "start_date": "2023-01-01",
  "end_date": "2024-01-31",
  "timezone": "America/Sao_Paulo",
  "video_duration": 3600,
  "pitch_time": 30
}
```

--------------------------------

### Live Users Response Format

Source: https://vturb.gitbook.io/analytics-api/pt/release-notes

Example JSON structure for the live users endpoint response, showing domain and active user counts.

```json
[
  {
    "domain": "example.com",
    "live_users": 15
  },
  {
    "domain": "test.com",
    "live_users": 8
  },
  {
    "domain": "another-site.com",
    "live_users": 3
  }
]
```

--------------------------------

### Query Documentation via HTTP GET

Source: https://vturb.gitbook.io/analytics-api/pt/autenticacao-da-api

Use this method to dynamically query documentation when information is not explicitly present or requires clarification. The question should be specific and self-contained.

```http
GET https://vturb.gitbook.io/analytics-api/pt/autenticacao-da-api.md?ask=<question>
```

--------------------------------

### New Endpoint: Session Stats Response Example

Source: https://vturb.gitbook.io/analytics-api/pt/release-notes

Example of a response payload for the /sessions/stats endpoint. This includes detailed session metrics, engagement rates, pitch time analysis, and conversion data.

```json
{
  "total_viewed": 200,
  "total_viewed_device_uniq": 180,
  "total_viewed_session_uniq": 190,
  "total_started": 250,
  "total_started_session_uniq": 230,
  "total_started_device_uniq": 220,
  "total_finished": 150,
  "total_finished_session_uniq": 140,
  "total_finished_device_uniq": 130,
  "engagement_rate": 75.56,
  "total_clicked": 50,
  "total_clicked_device_uniq": 45,
  "total_clicked_session_uniq": 40,
  "total_over_pitch": 30,
  "total_under_pitch": 10,
  "over_pitch_rate": 75,
  "total_conversions": 10,
  "overall_conversion_rate": 2.56,
  "total_amount_usd": 1000,
  "total_amount_brl": 1000,
  "total_amount_eur": 1000,
  "play_rate": 2.56
}
```

--------------------------------

### Get Live Users (Default)

Source: https://vturb.gitbook.io/analytics-api/pt/release-notes

Retrieves currently active users for the last 60 minutes. Requires a player ID.

```bash
GET /sessions/live_users?player_id=64a5c8072e6fd10009828db2
```

--------------------------------

### Get A/B Test Player Statistics

Source: https://vturb.gitbook.io/analytics-api/pt/release-notes

Retrieve comprehensive analytics for up to two players within an A/B test. This includes views, plays, finishes, clicks, conversions (with revenue in multiple currencies), engagement metrics, and derived rates. Dates can be specified per player or will default to the player's or test's start date.

```bash
curl -X POST https://{host}/comparison_groups/stats \
  -H 'X-Api-Token: <token>' \
  -H 'X-Api-Version: v1' \
  -H 'Content-Type: application/json' \
  -d '{
        "comparison_group_id": "699f9683dfeab82d6246e13b",
        "items": [
          {"player_id": "699f92f01dd8bb9e2b6aab3a", "start_date": "2026-02-26 00:41:00"},
          {"player_id": "699f9363c4b02ade5c5f1881", "start_date": "2026-02-26 00:41:00"}
        ]
      }'
```

--------------------------------

### Get Live Users (2 Hours)

Source: https://vturb.gitbook.io/analytics-api/pt/release-notes

Retrieves currently active users for the last 120 minutes. Requires a player ID.

```bash
GET /sessions/live_users?player_id=64a5c8072e6fd10009828db2&minutes=120
```

--------------------------------

### Get Live Users (30 Minutes)

Source: https://vturb.gitbook.io/analytics-api/pt/release-notes

Retrieves currently active users for the last 30 minutes. Requires a player ID.

```bash
GET /sessions/live_users?player_id=64a5c8072e6fd10009828db2&minutes=30
```

--------------------------------

### List A/B Tests (Comparison Groups)

Source: https://vturb.gitbook.io/analytics-api/pt/release-notes

Use this endpoint to retrieve a list of all A/B tests registered in your account. Results are ordered by creation date and can be filtered by optional start and end dates.

```bash
curl -X POST https://{host}/comparison_groups/list \
  -H 'X-Api-Token: <token>' \
  -H 'X-Api-Version: v1' \
  -H 'Content-Type: application/json' \
  -d '{"start_date":"2026-01-01 00:00:00"}'
```

--------------------------------

### Get Player Leaderboards

Source: https://vturb.gitbook.io/analytics-api/pt/analytics

Retrieves player leaderboards based on video engagement metrics for a given company. You can specify multiple leaderboards with different limits, start dates, and event types.

```APIDOC
## POST /events/leaderboard

### Description
Provides leaderboard rankings of players based on their video engagement metrics (views, plays, pauses, etc.) within specified time periods. Multiple leaderboards with different player limits can be requested in a single call.

### Method
POST

### Endpoint
/events/leaderboard

### Parameters
#### Request Body
- **company_id** (string) - Required - The ID of the company to search for
- **leaderboards** (array) - Required - An array of leaderboard configurations.
  - **leaderboard_limit** (integer) - Required - Maximum number of players to include in the leaderboard (minimum: 1)
  - **start_date** (string) - Required - Start date of the period for leaderboard data. This will be used as >=. Format examples "2023-10-26T18:24:05.000+00:00" or "2023-10-26 18:24:05 UTC" or "2023-10-26"
  - **end_date** (string) - Optional - End date of the period for leaderboard data. This will be used as <=. If not provided, will include data up to the current date. Format examples "2023-10-26T18:24:05.000+00:00" or "2023-10-26 18:24:05 UTC" or "2023-10-26"
  - **event** (string) - Optional - Event type to be used in the leaderboard ranking. Possible values: "started", "finished", "viewed", "clicked", "paused"
- **timezone** (string) - Optional - The timezone to use for date calculations (defaults to 'Etc/UCT' if not provided)

### Request Example
{
  "company_id": "your_company_id",
  "leaderboards": [
    {
      "leaderboard_limit": 10,
      "start_date": "2023-10-01",
      "event": "viewed"
    },
    {
      "leaderboard_limit": 5,
      "start_date": "2023-10-01",
      "end_date": "2023-10-25",
      "event": "paused"
    }
  ],
  "timezone": "America/Los_Angeles"
}

### Response
#### Success Response (200)
- **leaderboard_name** (string) - Name of the leaderboard (includes the limit)
- **event** (string) - Event type that was used to rank the leaderboard
- **leaderboards** (array) - Array of player data for the leaderboard.
  - **player_id** (string) - Unique identifier for the player
  - **total_plays** (integer) - Total number of video plays for this player
  - **uniq_plays** (integer) - Number of unique plays (by session) for this player
  - **uniq_device_plays** (integer) - Number of unique device plays for this player

#### Response Example
{
  "leaderboard_name": "viewed_10",
  "event": "viewed",
  "leaderboards": [
    {
      "player_id": "player_abc",
      "total_plays": 150,
      "uniq_plays": 120,
      "uniq_device_plays": 110
    },
    {
      "player_id": "player_xyz",
      "total_plays": 130,
      "uniq_plays": 115,
      "uniq_device_plays": 105
    }
  ]
}

ERROR HANDLING:
- 400: Bad request: the request was bad formatted and some of the arguments were missing or wrong, look at the response body for more information.
- 401: Unauthorized
```

--------------------------------

### Get Total User Clicks by Time

Source: https://vturb.gitbook.io/analytics-api/pt/analytics

This snippet defines an API endpoint to retrieve the total number of user clicks grouped by the second in which they occurred within a video. It requires player ID, start date, and end date for the query.

```json
{
  "openapi": "3.0.2",
  "info": {
    "title": "Public Analytics Ruby API",
    "version": "v3"
  },
  "tags": [
    {
      "name": "analytics",
      "description": "Namespace for all routes that are used broadly across vturb, this ultimately delivers the data to the front-end for our clients.\n"
    }
  ],
  "servers": [
    {
      "description": "Production Server",
      "url": "https://analytics.vturb.net"
    }
  ],
  "security": [
    {
      "apiToken": [],
      "apiVersion": []
    }
  ],
  "components": {
    "securitySchemes": {
      "apiToken": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Token",
        "description": "Access the application and copy your api token, then, just set the header `X-Api-Token` with it."
      }
    },
    "schemas": {
      "GroupedTimed": {
        "type": "object",
        "properties": {
          "timed": {
            "type": "integer",
            "description": "The second of the video that the user reached\n"
          },
          "total_users": {
            "type": "integer",
            "description": "The total of users that reached the timed\n"
          }
        }
      }
    }
  },
  "paths": {
    "/clicks/total_by_company_timed": {
      "post": {
        "tags": [
          "analytics"
        ],
        "summary": "Returns the total of user clicks at a time in seconds related to the video",
        "description": "Returns an object containing the all the clicks grouped by the time in seconds it happened related to the video.\n",
        "operationId": "totalByCompanyTimed",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true,
                "required": [
                  "player_id",
                  "start_date",
                  "end_date"
                ],
                "properties": {
                  "player_id": {
                    "type": "string",
                    "description": "The ID of the player to search for"
                  },
                  "start_date": {
                    "type": "string",
                    "format": "date",
                    "description": "Start date of the period for event querying. This will be used as >=. Format examples \"2023-10-26T18:24:05.000+00:00\" or \"2023-10-26 18:24:05 UTC\"
                  },
                  "end_date": {
                    "type": "string",
                    "format": "date",
                    "description": "End date of the period for event querying. This will be used as <=. Format examples \"2023-10-26T18:24:05.000+00:00\" or \"2023-10-26 18:24:05 UTC\"
                  },
                  "timezone": {
                    "type": "string",
                    "description": "The timezone to use for the date filtering"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/GroupedTimed"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request: the request was bad formatted and some of the arguments were missing or wrong, look at the response body for more information.\n"
          },
          "401": {
            "description": "Unauthorized, missing proper X-Api-Token or X-Api-Version"
          }
        }
      }
    }
  }
}
```

--------------------------------

### Get Session Statistics Grouped by Field by Day

Source: https://vturb.gitbook.io/analytics-api/pt/analytics

Use this endpoint to retrieve session statistics for a specific player, grouped by a chosen field, within a date range, and broken down by day. Ensure you provide the player ID, start and end dates, the field for grouping, and the video duration.

```json
{
  "openapi": "3.0.2",
  "info": {
    "title": "Public Analytics Ruby API",
    "version": "v3"
  },
  "tags": [
    {
      "name": "analytics",
      "description": "Namespace for all routes that are used broadly across vturb, this ultimately delivers the data to the front-end for our clients.\n"
    }
  ],
  "servers": [
    {
      "description": "Production Server",
      "url": "https://analytics.vturb.net"
    }
  ],
  "security": [
    {
      "apiToken": [],
      "apiVersion": []
    }
  ],
  "components": {
    "securitySchemes": {
      "apiToken": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Token",
        "description": "Access the application and copy your api token, then, just set the header `X-Api-Token` with it."
      }
    },
    "schemas": {
      "StatsByFieldByDay": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "date_key": {
              "type": "string",
              "format": "date"
            },
            "field": {
              "type": "string"
            },
            "video_duration": {
              "type": "integer"
            },
            "timezone": {
              "type": "string"
            },
            "pitch_time": {
              "type": "integer"
            },
            "total_viewed": {
              "type": "integer"
            },
            "total_viewed_device_uniq": {
              "type": "integer"
            },
            "total_started": {
              "type": "integer"
            },
            "total_started_session_uniq": {
              "type": "integer"
            },
            "total_started_device_uniq": {
              "type": "integer"
            },
            "total_finished": {
              "type": "integer"
            },
            "total_finished_session_uniq": {
              "type": "integer"
            },
            "total_finished_device_uniq": {
              "type": "integer"
            },
            "engagement_rate": {
              "type": "number"
            },
            "total_clicked": {
              "type": "integer"
            },
            "total_clicked_device_uniq": {
              "type": "integer"
            },
            "total_clicked_session_uniq": {
              "type": "integer"
            },
            "total_viewed_session_uniq": {
              "type": "integer"
            },
            "grouped_field": {
              "type": "string"
            },
            "total_over_pitch": {
              "type": "integer"
            },
            "total_under_pitch": {
              "type": "integer"
            },
            "over_pitch_rate": {
              "type": "integer"
            },
            "total_conversions": {
              "type": "integer"
            },
            "overall_conversion_rate": {
              "type": "number"
            },
            "total_amount_usd": {
              "type": "integer"
            },
            "total_amount_brl": {
              "type": "integer"
            },
            "total_amount_eur": {
              "type": "integer"
            },
            "play_rate": {
              "type": "number"
            }
          }
        }
      }
    }
  },
  "paths": {
    "/sessions/stats_by_field_by_day": {
      "post": {
        "tags": [
          "analytics"
        ],
        "summary": "Returns statistics grouped by a specified field broke by day",
        "description": "Returns statistics for sessions grouped by a specified field for a given company and player within a date range and broke by day.\n",
        "operationId": "statsByFieldByDay",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "player_id",
                  "start_date",
                  "end_date",
                  "field",
                  "video_duration"
                ],
                "properties": {
                  "player_id": {
                    "type": "string",
                    "description": "The ID of the player to search for"
                  },
                  "start_date": {
                    "type": "string",
                    "format": "date",
                    "description": "Start date of the period for event querying. This will be used as >=. Format examples \"2023-10-26T18:24:05.000+00:00\" or \"2023-10-26 18:24:05 UTC\" or \"2023-10-26\"
                  },
                  "end_date": {
                    "type": "string",
                    "format": "date",
                    "description": "End date of the period for event querying. This will be used as <=. Format examples \"2023-10-26T18:24:05.000+00:00\" or \"2023-10-26 18:24:05 UTC\" or \"2023-10-26\"
                  },
                  "field": {
                    "type": "string",
                    "description": "The field to group the statistics by"
                  },
                  "video_duration": {
                    "type": "integer",
                    "description": "The total duration of the video in seconds"
                  },
                  "timezone": {
                    "type": "string",
                    "description": "The timezone to use for the date filtering"
                  },
                  "pitch_time": {
                    "type": "integer",
                    "description": "The time in seconds that the video must be watched to be considered a pitch"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatsByFieldByDay"
                }
              }
            }
          },
          "400": {
            "description": "Bad request: the request was bad formatted and some of the arguments were missing or wrong, look at the response body for more information.\n"
          },
          "401": {
            "description": "Unauthorized, missing proper X-Api-Token or X-Api-Version"
          }
        }
      }
    }
  }
}
```

--------------------------------

### Get Daily Session Statistics

Source: https://vturb.gitbook.io/analytics-api/pt/release-notes

Retrieves comprehensive daily analytics for user sessions within a specified date range. This endpoint provides detailed metrics such as total views, starts, finishes, clicks, unique users/devices, engagement rates, pitch limit analysis, and conversion tracking with multi-currency values.

```APIDOC
## GET /sessions/stats_by_day

### Description
Retrieves daily aggregated statistics for user sessions, including views, starts, finishes, clicks, unique users/devices, engagement rates, pitch limit analysis, and conversion tracking with multi-currency values. Supports filtering by date range and timezone.

### Method
GET

### Endpoint
/sessions/stats_by_day

### Parameters
#### Query Parameters
- **player_id** (string) - Required - The ID of the player to retrieve stats for.
- **start_date** (string) - Required - The start date for the data range (YYYY-MM-DD).
- **end_date** (string) - Required - The end date for the data range (YYYY-MM-DD).
- **timezone** (string) - Optional - The timezone to use for date aggregation (e.g., "America/Sao_Paulo"). Defaults to UTC if not provided.
- **video_duration** (integer) - Optional - The duration of the video in seconds, used for engagement calculations.
- **pitch_time** (integer) - Optional - The pitch time threshold in seconds, used for pitch limit analysis.

### Request Example
```json
{
  "player_id": "65fb3c74ab21c70007b3e0dd",
  "start_date": "2023-01-01",
  "end_date": "2023-01-31",
  "timezone": "America/Sao_Paulo",
  "video_duration": 3600,
  "pitch_time": 30
}
```

### Response
#### Success Response (200)
An array of objects, where each object represents the aggregated stats for a single day.
- **date_key** (string) - The date for which the stats are aggregated (YYYY-MM-DD).
- **total_viewed** (integer) - Total number of times the content was viewed.
- **total_viewed_device_uniq** (integer) - Total number of unique devices that viewed the content.
- **total_viewed_session_uniq** (integer) - Total number of unique sessions that viewed the content.
- **total_started** (integer) - Total number of times the content playback was started.
- **total_started_session_uniq** (integer) - Total number of unique sessions that started playback.
- **total_started_device_uniq** (integer) - Total number of unique devices that started playback.
- **total_finished** (integer) - Total number of times the content playback was finished.
- **total_finished_session_uniq** (integer) - Total number of unique sessions that finished playback.
- **total_finished_device_uniq** (integer) - Total number of unique devices that finished playback.
- **engagement_rate** (float) - The calculated engagement rate based on average view time.
- **total_clicked** (integer) - Total number of clicks.
- **total_clicked_device_uniq** (integer) - Total number of unique devices that clicked.
- **total_clicked_session_uniq** (integer) - Total number of unique sessions that clicked.
- **total_over_pitch** (integer) - Number of users who watched above the pitch time limit.
- **total_under_pitch** (integer) - Number of users who watched below the pitch time limit.
- **over_pitch_rate** (float) - The rate of users watching above the pitch time limit.
- **total_conversions** (integer) - Total number of conversions.
- **overall_conversion_rate** (float) - The overall conversion rate.
- **total_amount_usd** (integer) - Total conversion amount in USD.
- **total_amount_brl** (integer) - Total conversion amount in BRL.
- **total_amount_eur** (integer) - Total conversion amount in EUR.
- **play_rate** (float) - The percentage of viewers who started playing after viewing.

#### Response Example
```json
[
  {
    "date_key": "2023-01-01",
    "total_viewed": 200,
    "total_viewed_device_uniq": 180,
    "total_viewed_session_uniq": 190,
    "total_started": 250,
    "total_started_session_uniq": 230,
    "total_started_device_uniq": 220,
    "total_finished": 150,
    "total_finished_session_uniq": 140,
    "total_finished_device_uniq": 130,
    "engagement_rate": 75.56,
    "total_clicked": 50,
    "total_clicked_device_uniq": 45,
    "total_clicked_session_uniq": 40,
    "total_over_pitch": 30,
    "total_under_pitch": 10,
    "over_pitch_rate": 75.0,
    "total_conversions": 10,
    "overall_conversion_rate": 2.56,
    "total_amount_usd": 1000,
    "total_amount_brl": 1000,
    "total_amount_eur": 1000,
    "play_rate": 2.56
  }
]
```
```

--------------------------------

### Exemplo de Requisição cURL

Source: https://vturb.gitbook.io/analytics-api/pt/autenticacao-da-api

Demonstra como realizar uma requisição POST autenticada para a API usando cURL. Certifique-se de substituir 'YOUR_API_TOKEN' pelo seu token real.

```bash
curl -X POST 'https://analytics.vturb.net/conversions/active_platforms' \
  -H 'X-Api-Token: YOUR_API_TOKEN' \
  -H 'X-Api-Version: v1' \
  -H 'Content-Type: application/json' \
  -d '{
    "start_date": "2023-10-26 18:24:05",
    "timezone": "America/Sao_Paulo"
  }'
```

--------------------------------

### Filter Players by Creation Date

Source: https://vturb.gitbook.io/analytics-api/pt/release-notes

Use the `start_date` parameter to filter players created on or after a specific date. The `timezone` parameter can be specified to adjust date filtering.

```bash
GET /players/list?start_date=2023-10-01&timezone=America/Sao_Paulo
```

--------------------------------

### Requisição Autenticada com Ruby

Source: https://vturb.gitbook.io/analytics-api/pt/autenticacao-da-api

Exemplo de como efetuar uma requisição POST autenticada utilizando as bibliotecas Net::HTTP e JSON em Ruby. Os cabeçalhos 'X-Api-Token' e 'X-Api-Version' são essenciais.

```ruby
require 'net/http'
require 'json'
require 'uri'

uri = URI('https://analytics.vturb.net/conversions/active_platforms')
headers = {
  'X-Api-Token' => 'YOUR_API_TOKEN',
  'X-Api-Version' => 'v1',
  'Content-Type' => 'application/json'
}
payload = {
  start_date: '2023-10-26 18:24:05',
  timezone: 'America/Sao_Paulo'
}

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri.path, headers)
request.body = payload.to_json

response = http.request(request)
puts JSON.parse(response.body)
```

--------------------------------

### Filter Players by Creation Date

Source: https://vturb.gitbook.io/analytics-api/pt/release-notes

Retrieves a list of players created on or after a specified start date, with optional end date and timezone filtering.

```APIDOC
## GET /players/list?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD&timezone=Timezone

### Description
Retrieves a list of players created on or after a specified start date, with optional end date and timezone filtering.

### Method
GET

### Endpoint
/players/list

### Parameters
#### Query Parameters
- **start_date** (string) - Optional - The start date for filtering players. Uses '>=' comparison. Supports formats like "2023-10-26T18:24:05.000+00:00" or "2023-10-26 18:24:05 UTC".
- **end_date** (string) - Optional - The end date for filtering players. Uses '<=' comparison. Supports the same date formats as start_date.
- **timezone** (string) - Optional - The timezone to be used for date filtering. Defaults to 'Etc/UCT' if not specified.

### Response
#### Success Response (200)
- **id** (string) - The player's unique identifier.
- **name** (string) - The player's name.
- **pitch_time** (integer) - The time the player was pitched.
- **duration** (integer) - The duration associated with the player.
- **created_at** (string) - The timestamp when the player was created.

### Response Example
{
  "example": "[
  {
    "id": "player1",
    "name": "Meu Player",
    "pitch_time": 0,
    "duration": 3600,
    "created_at": "2025-07-18T10:00:00Z"
  }
]"
}
```

--------------------------------

### List Players (Basic Request)

Source: https://vturb.gitbook.io/analytics-api/pt/release-notes

A basic request to the /players/list endpoint without any filters. This is the unchanged, previous functionality.

```bash
GET /players/list
```

--------------------------------

### /comparison_groups/list

Source: https://vturb.gitbook.io/analytics-api/pt/release-notes

Lists the registered A/B tests (comparison groups) in your account. Each item includes the test name, participating players with their traffic percentages, and start/end dates. Results are ordered by creation date (most recent first) and can be filtered by optional start_date and end_date.

```APIDOC
## POST /comparison_groups/list

### Description
Lists the A/B tests (comparison groups) registered in your account. Each item includes the test name, participating players with their traffic percentages, and start/end dates. Results are ordered by creation date (most recent first) and can be filtered by optional `start_date` and `end_date`.

### Method
POST

### Endpoint
/comparison_groups/list

### Parameters
#### Query Parameters
- **start_date** (string) - Optional - Filter results by start date (YYYY-MM-DD HH:MM:SS).
- **end_date** (string) - Optional - Filter results by end date (YYYY-MM-DD HH:MM:SS).

### Request Example
```json
{
  "start_date": "2026-01-01 00:00:00"
}
```

### Response
#### Success Response (200)
- **name** (string) - The name of the A/B test.
- **player_ids** (array) - An array of player IDs participating in the test.
- **started_at** (string) - The start date of the A/B test.
- **finished_at** (string or null) - The end date of the A/B test, or null if it's ongoing.

#### Response Example
```json
{
  "comparison_groups": [
    {
      "id": "...",
      "name": "Test Name",
      "player_ids": ["player_id_1", "player_id_2"],
      "started_at": "2026-02-26 00:41:00",
      "finished_at": null
    }
  ]
}
```
```

--------------------------------

### Get Traffic Origin Statistics by Field

Source: https://vturb.gitbook.io/analytics-api/pt/analytics

Returns statistics for traffic origin grouped by a specified query key for a given company and player within a date range.

```APIDOC
## POST /traffic_origin/stats

### Description
Returns statistics for traffic origin grouped by a specified query key for a given company and player within a date range.

### Method
POST

### Endpoint
/traffic_origin/stats

### Parameters
#### Query Parameters
- **player_id** (string) - Required - The ID of the player to search for
- **start_date** (string) - Required - Start date of the period for event querying. This will be used as >=. Format examples "2023-10-26T18:24:05.000+00:00" or "2023-10-26 18:24:05 UTC" or "2023-10-26"
- **end_date** (string) - Required - End date of the period for event querying. This will be used as <=. Format examples "2023-10-26T18:24:05.000+00:00" or "2023-10-26 18:24:05 UTC" or "2023-10-26"
- **query_key** (string) - Required - The query key to group the statistics by
- **video_duration** (integer) - Required - The total duration of the video in seconds
- **timezone** (string) - Optional - The timezone to use for the date filtering
- **pitch_time** (integer) - Optional - The time in seconds that the video must be watched to be considered a pitch

### Request Body
This endpoint does not explicitly define a request body schema in the provided OpenAPI specification, but it expects parameters to be sent in the request body.

### Response
#### Success Response (200)
- **company_id** (string) - The ID of the company.
- **player_id** (string) - The ID of the player.
- **field** (string) - The field by which statistics are grouped.
- **video_duration** (integer) - The total duration of the video in seconds.
- **timezone** (string) - The timezone used for date filtering.
- **pitch_time** (integer) - The time in seconds a video must be watched to be considered a pitch.
- **total_viewed** (integer) - Total number of times the video was viewed.
- **total_viewed_device_uniq** (integer) - Total number of unique devices that viewed the video.
- **total_started** (integer) - Total number of times the video playback was started.
- **total_started_session_uniq** (integer) - Total number of unique sessions where video playback was started.
- **total_started_device_uniq** (integer) - Total number of unique devices where video playback was started.
- **total_finished** (integer) - Total number of times the video playback was finished.
- **total_finished_session_uniq** (integer) - Total number of unique sessions where video playback was finished.
- **total_finished_device_uniq** (integer) - Total number of unique devices where video playback was finished.
- **engagement_rate** (number) - The engagement rate of the video.
- **total_clicked** (integer) - Total number of times a click action was registered.
- **total_clicked_device_uniq** (integer) - Total number of unique devices that registered a click action.
- **total_clicked_session_uniq** (integer) - Total number of unique sessions that registered a click action.
- **total_viewed_session_uniq** (integer) - Total number of unique sessions where the video was viewed.
- **grouped_field** (string) - The value of the field by which statistics are grouped.
- **total_over_pitch** (integer) - Total times the video was watched beyond the pitch time.
- **total_under_pitch** (integer) - Total times the video was watched before the pitch time.
- **over_pitch_rate** (integer) - The rate at which the video was watched beyond the pitch time.
- **total_conversions** (integer) - Total number of conversions.
- **overall_conversion_rate** (number) - The overall conversion rate.
- **total_amount_usd** (integer) - Total amount in USD.
- **total_amount_brl** (integer) - Total amount in BRL.
- **total_amount_eur** (integer) - Total amount in EUR.
- **play_rate** (number) - The play rate of the video.

#### Response Example
```json
{
  "company_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "player_id": "player123",
  "field": "country",
  "video_duration": 60,
  "timezone": "UTC",
  "pitch_time": 30,
  "total_viewed": 1000,
  "total_viewed_device_uniq": 500,
  "total_started": 900,
  "total_started_session_uniq": 450,
  "total_started_device_uniq": 480,
  "total_finished": 700,
  "total_finished_session_uniq": 350,
  "total_finished_device_uniq": 370,
  "engagement_rate": 0.85,
  "total_clicked": 50,
  "total_clicked_device_uniq": 40,
  "total_clicked_session_uniq": 45,
  "total_viewed_session_uniq": 480,
  "grouped_field": "USA",
  "total_over_pitch": 600,
  "total_under_pitch": 100,
  "over_pitch_rate": 80,
  "total_conversions": 20,
  "overall_conversion_rate": 0.02,
  "total_amount_usd": 100,
  "total_amount_brl": 500,
  "total_amount_eur": 90,
  "play_rate": 0.9
}
```

#### Error Response (400)
Bad request: the request was bad formatted and some of the arguments were missing or wrong, look at the response body for more information.

#### Error Response (401)
Unauthorized, missing proper X-Api-Token or X-Api-Version
```

--------------------------------

### Get User Engagement Data

Source: https://vturb.gitbook.io/analytics-api/pt/release-notes

Requests user engagement data for a given player and time period, used in conjunction with custom metrics to calculate retention rates.

```json
{
  "start_date": "2023-10-26 18:24:05",
  "end_date": "2023-11-26 18:24:05",
  "player_id": "65fb3c74ab21c70007b3e0dd",
  "video_duration": 3600,
  "timezone": "America/Sao_Paulo"
}
```
Tokens:
Raw