Find a player's ID

Almost every query takes a player_id: the ID of a player in your VTurb account, 24 hexadecimal characters. GET /players/list returns it, together with the duration of the player's video and its pitch time, which the retention and pitch queries use.

List your players

The request needs only the authentication headers:

curl 'https://analytics.vturb.com/players/list' \
  -H "X-Api-Token: $VTURB_API_TOKEN" \
  -H 'X-Api-Version: v1' \
  -H 'User-Agent: my-integration/1.0'

[
  {
    "id": "64a5c8072e6fd10009828db2",
    "name": "Black Friday VSL",
    "pitch_time": 1260,
    "duration": 2340,
    "created_at": "2025-07-18 10:00:00"
  }
]

Deleted players are not listed, nor are players whose video was deleted.

Search by name

With many players, filter by name instead of paging through all of them:

curl 'https://analytics.vturb.com/players/list?name=black%20friday&name_match=starts_with' \
  -H "X-Api-Token: $VTURB_API_TOKEN" \
  -H 'X-Api-Version: v1' \
  -H 'User-Agent: my-integration/1.0'

• name is trimmed of surrounding spaces and then needs 3 to 128 characters. It ignores case, accented letters included (É matches é, not e). %, _ and \ are matched literally.
• name_match sets how: contains (the default), starts_with, ends_with or exact. It requires name.

Filter by creation date

start_date and end_date keep only the players created in that range, read in timezone (UTC when you leave it out):

curl -G 'https://analytics.vturb.com/players/list' \
  --data-urlencode 'start_date=2026-09-01 00:00:00' \
  --data-urlencode 'end_date=2026-09-30 23:59:59' \
  --data-urlencode 'timezone=America/Sao_Paulo' \
  -H "X-Api-Token: $VTURB_API_TOKEN" \
  -H 'X-Api-Version: v1' \
  -H 'User-Agent: my-integration/1.0'

Both dates are optional, and each is written YYYY-MM-DD HH:MM:SS.

Keep the IDs

A player's ID does not change, so look it up once and store it with your report or integration. duration and pitch_time follow the player's current configuration: read them again when the video or the pitch changes.

Next: build a daily report or measure retention and the pitch for the player you found.