# Initiate a new tracking session

Initiates a new tracking session for analytics and user behavior tracking.

Creates a new tracking session with a unique ID and current timestamp,
and sets it as both a cookie and header in the response. The session data is
base64-encoded JSON that contains the session ID, start timestamp, and source information.

The tracking session is used to correlate user actions across different API requests
and provides analytics capabilities for understanding user behavior.

If the client can't process cookies or uses a library that doesn't support set-cookie headers,
the client should extract the returned session value and manually add it as a header in
subsequent requests.


Args:

    response: The HTTP response object to which the cookie and header will be added
    user_id: Optional user identifier to track users across multiple sessions

Returns:

    ResultResponse[TrackingSession]: The newly created tracking session object with session ID, timestamp, and source.

Endpoint: POST /playouts/{playout_id}/tracking/session
Version: 2025-09-02

## Path parameters:

  - `playout_id` (string, required)

## Query parameters:

  - `user_id` (string)
    Optional user ID to track users across sessions

## Header parameters:

  - `X-API-Key` (string, required)
    API access key for authorized use of the checkout endpoints. Partners, please contact Transfermedia to retrieve a valid key.

  - `X-JAY-TRACKING` (string)
    Tracking session header for user tracking and analytics. This is set by the /playouts/{playout_id}/tracking/session endpoint.
    Example: "eyJzZXNzaW9uX2lkIjoiZXhhbXBsZS1zZXNzaW9uLWlkLTEyMzQiLCJzdGFydF90aW1lIjoiMjAyNS0wMS0wMVQxMjowMDowMC4wMDAwMDAiLCJzb3VyY2UiOiJqYXkuYXBpLnBsYXlvdXQuZXhhbXBsZSJ9"

## Response 200 fields (application/json):

  - `data` (object)
    The response data.
    Example: {"sessionId":"550e8400-e29b-41d4-a716-446655440000","startTime":"2023-01-15T14:30:24.123456","source":"jay.api.playout.1.0.0","userId":"user-123456","providerName":"netflix"}

  - `data.sessionId` (string, required)
    Unique identifier for the tracking session
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `data.startTime` (string, required)
    ISO 8601 formatted timestamp of when the session started
    Example: "2023-01-15T14:30:24.123456"

  - `data.source` (string, required)
    Identifier of the system or API version that created this session
    Example: "jay.api.playout.1.0.0"

  - `data.userId` (string)
    Optional identifier to track users across multiple sessions
    Example: "user-123456"

  - `data.providerName` (string)
    Name of the content provider, automatically extracted from the playout path
    Example: "netflix"

  - `nextToken` (string)
    The token, which can be used to retrieve the next page of data.

  - `error` (object)
    Details of the error that occurred during the API request, including error code and message. This field is only present when the request results in an error.

  - `error.code` (integer, required)
    The API error code
    Enum: 1001, 1002, 1003, 1004, 1005, 1006, 1007, 1008, 1009, 1010, 1011, 1012, 1013, 1014, 2001, 2002, 2003, 2004, 2005, 2006, 2008, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025, 3000, 3001, 3002, 3003, 3004, 3005, 3006, 3007, 4001, 4002, 5001, 5002, 5003, 5004, 200, 201, 202, 204, 400, 401, 403, 404, 405, 406, 422, 423, 501, 503

  - `error.message` (string, required)
    The API error message.

  - `error.details` (any)
    The HTTP error details.

## Response 422 fields (application/json):

  - `detail` (array)

  - `detail.loc` (array, required)

  - `detail.msg` (string, required)

  - `detail.type` (string, required)