### 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= ``` -------------------------------- ### 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: ' \ -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: ' \ -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" } ```