> For the complete documentation index, see [llms.txt](https://docs.ggwp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ggwp.com/api-docs-contextual-information/telemetry.md).

# Telemetry

\[ Base URL: `api.ggwp.com`]

`POST` /data/v1/ingest

## **Description**

Reports gameplay telemetry data corresponding to an individual match or session, tracking specific player actions through the course of the game. This information can be used to validate certain incidents (eg: AFK, friendly fire, intentional feeding…) and to provide additional context when reviewing incidents or players in GGWP’s moderation tool.

Some common telemetry events that games are logging would be:

* Session start/end times
* Player positions
* Player actions - movements, attacks, plays, item pickups, deaths, revives, etc.

## **Parameters**

`body`: Dictionary containing the following fields:

* **type**: `telemetry`
* **session\_id**: unique identifier of the match.
* **start\_time**: match start time in *YYYY-MM-DD HH:MM:SS* format, in UTC.
* **end\_time**: match end time in *YYYY-MM-DD HH:MM:SS* format, in UTC.
* **events**: list of event logs, each represented by a dictionary.
* Sample Call

  ```bash
  curl --request POST 'https://api.ggwp.com/data/v1/ingest' \
  --header 'x-api-key: api_key' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "type": "telemetry",
    "session_id": "<id1>",	
    "start_time": "2022-01-25 09:44:00",
    "end_time": "2022-01-25 10:12:23",
    "events": [
      {
        "event_type": "playerSessionStart", 
        "timestamp": "2022-01-25 09:43:35",
        "user_id": "<id1>",
        "team_id": "1",
        "event_details": {}
      },
      {
        "event_type": "playerPosition", 
        "timestamp": "2022-01-25 09:44:30",
        "user_id": "<id1>",
        "team_id": "1",
        "event_details": {
          "location": {
            "x": 103450,
            "y": 200560,
            "z": 102
          }
        }
      },
      {
        "event_type": "playerAction", 
        "timestamp": "2022-01-25 09:45:13",
        "user_id": "<id1>",
        "team_id": "1",
        "event_details": {
          "action_type": "attack",   
          "action_target": "<id3>",
          "location": {
            "x": 421450,
            "y": 113460,
            "z": 10
          },
          "damage": 50,
          "weapon": "gun"
        }
      },
      ...
    ] 
  }'
  ```

## **Output**

* 200 - successful operation

  ```json
  {
    "status": "success"
  }
  ```
* 400
  * Error response. The event has not been inserted into the system. This error is thrown in the following cases:
    * `Invalid Body. Expected JSON input`
      * Data payload is not JSON format
    * `Data payload too large`
      * Data payload exceeds 1MB in size
* 403
  * Invalid or missing API key.
* 500
  * Error response. The event has not been inserted into the system. There was some error on the server while processing the request.