Analytics Events

Use this endpoint to send custom analytics events to Teak from your game server. Events submitted through this API are usable in segmentation the same way SDK-reported events are.

This is primarily useful for game architectures where events are generated server-side and forwarded to third parties, rather than being generated by the game client.

Sending a Single Event

Endpoint	https://api.gocarrot.com/v2/analytics_events
Request Type	POST
Content-Type	application/json or application/x-www-form-urlencoded
Rate Limiting	100 requests per second

Endpoint

https://api.gocarrot.com/v2/analytics_events

Request Type

POST

Content-Type

application/json or application/x-www-form-urlencoded

Rate Limiting

100 requests per second

Required Parameters

Name Description

Name	Description
game_id	Your Teak App ID
secret_key	Your Teak Server Secret
user_id	The Game Assigned Player ID of the player this event is for. This must match the value provided by the game client’s Teak SDK integration.
action_type	The event type string (e.g. "level_up", "purchase"). Corresponds to the `action_type` parameter in the SDK’s `incrementEvent`.

game_id

Your Teak App ID

secret_key

Your Teak Server Secret

user_id

The Game Assigned Player ID of the player this event is for. This must match the value provided by the game client’s Teak SDK integration.

action_type

The event type string (e.g. "level_up", "purchase"). Corresponds to the action_type parameter in the SDK’s incrementEvent.

Optional Parameters

Name Description

Name	Description
object_type	The event category string (e.g. "character", "item"). Corresponds to the `object_type` parameter in the SDK’s `incrementEvent`.
object_instance_id	Additional context for the event (e.g. "warrior", "sword"). Corresponds to the `object_instance_id` parameter in the SDK’s `incrementEvent`.
event_count	The number of times this event occurred. Used for aggregate event reporting. Defaults to 1 if omitted.
value	An arbitrary numeric value associated with this event. For example, the total coin cost across all occurrences. Defaults to 1 if omitted.
sum_of_squares	The sum of squared per-occurrence values for this event. Used for statistical calculations (variance/standard deviation). Defaults to 1 if omitted.
client_ip	The player’s IP address. Used for geographic segmentation. Takes highest priority for geo resolution. If both `client_ip` and `country_code` are provided, `client_ip` is used.
country_code	ISO 3166-1 alpha-2 country code for the player (e.g. "US", "GB"). Used for geographic segmentation when `client_ip` is not provided. If neither `client_ip` nor `country_code` is provided, the player’s location from their most recent SDK session is used automatically.

object_type

The event category string (e.g. "character", "item"). Corresponds to the object_type parameter in the SDK’s incrementEvent.

object_instance_id

Additional context for the event (e.g. "warrior", "sword"). Corresponds to the object_instance_id parameter in the SDK’s incrementEvent.

event_count

The number of times this event occurred. Used for aggregate event reporting. Defaults to 1 if omitted.

value

An arbitrary numeric value associated with this event. For example, the total coin cost across all occurrences. Defaults to 1 if omitted.

sum_of_squares

The sum of squared per-occurrence values for this event. Used for statistical calculations (variance/standard deviation). Defaults to 1 if omitted.

client_ip

The player’s IP address. Used for geographic segmentation. Takes highest priority for geo resolution. If both client_ip and country_code are provided, client_ip is used.

country_code

ISO 3166-1 alpha-2 country code for the player (e.g. "US", "GB"). Used for geographic segmentation when client_ip is not provided. If neither client_ip nor country_code is provided, the player’s location from their most recent SDK session is used automatically.

Success Response

Status Code

200

Response Body

JSON dictionary.

status

'ok'

Example

{
  "status": "ok"
}

Error Responses

Not Found

Status Code	404
Response Body	JSON dictionary with 'status' and 'errors' keys. 'status' will be 'error'. 'errors' will be a dictionary indicating which resource was not found.

Status Code

404

Response Body

JSON dictionary with 'status' and 'errors' keys. 'status' will be 'error'. 'errors' will be a dictionary indicating which resource was not found.

Example

{"status":"error","errors":{"user_id":["could not be found"]}}

Rate Limit Response

Status Code	429
Response Body	JSON dictionary with 'status' and 'errors' keys. 'status' will be 'rate_limit'. 'errors' will contain the key 'rate_limit'

Status Code

429

Response Body

JSON dictionary with 'status' and 'errors' keys. 'status' will be 'rate_limit'. 'errors' will contain the key 'rate_limit'

Example

{"status":"rate_limit","errors":{"rate_limit":["/v2/analytics_events may only be called 100 times per second. Please wait a second and try again"]}}

Batch Sending

Endpoint	https://api.gocarrot.com/v2/analytics_events/batch
Request Type	POST
Content-Type	application/json or application/x-www-form-urlencoded
Rate Limiting	100 requests per second
Batch Size	Up to 100 events per request

Endpoint

https://api.gocarrot.com/v2/analytics_events/batch

Request Type

POST

Content-Type

application/json or application/x-www-form-urlencoded

Rate Limiting

100 requests per second

Batch Size

Up to 100 events per request

Use this endpoint to send multiple analytics events in a single request. This is more efficient than making individual requests when you need to report many events at once.

Required Parameters

Name	Description
game_id	Your Teak App ID
secret_key	Your Teak Server Secret
events	An array of event objects. Maximum of 100 events per request.

Name

Description

game_id

Your Teak App ID

secret_key

Your Teak Server Secret

events

An array of event objects. Maximum of 100 events per request.

Event Object Structure

Name Description

Name	Description
user_id	Required. The Game Assigned Player ID of the player this event is for.
action_type	Required. The event type string.
object_type	The event category string.
object_instance_id	Additional context for the event.
event_count	The number of times this event occurred. Defaults to 1 if omitted.
value	An arbitrary numeric value associated with this event. For example, the total coin cost across all occurrences. Defaults to 1 if omitted.
sum_of_squares	The sum of squared per-occurrence values for this event. Defaults to 1 if omitted.
client_ip	The player’s IP address for geographic segmentation. Takes highest priority for geo resolution.
country_code	ISO 3166-1 alpha-2 country code for geographic segmentation. Used when `client_ip` is not provided. Falls back to last SDK session location if neither is specified.

user_id

Required. The Game Assigned Player ID of the player this event is for.

action_type

Required. The event type string.

object_type

The event category string.

object_instance_id

Additional context for the event.

event_count

The number of times this event occurred. Defaults to 1 if omitted.

value

An arbitrary numeric value associated with this event. For example, the total coin cost across all occurrences. Defaults to 1 if omitted.

sum_of_squares

The sum of squared per-occurrence values for this event. Defaults to 1 if omitted.

client_ip

The player’s IP address for geographic segmentation. Takes highest priority for geo resolution.

country_code

ISO 3166-1 alpha-2 country code for geographic segmentation. Used when client_ip is not provided. Falls back to last SDK session location if neither is specified.

Example Request

{
  "game_id": "your_teak_app_id",
  "secret_key": "your_server_secret",
  "events": [
    {
      "user_id": "player_123",
      "action_type": "level_up",
      "object_type": "character",
      "object_instance_id": "warrior",
      "event_count": 1
    },
    {
      "user_id": "player_456",
      "action_type": "spin",
      "object_type": "Mr. Bling Bling's Slots",
      "object_instance_id": "bet_5000",
      "event_count": 10,
      "value": 50000,
      "sum_of_squares": 250000000,
      "country_code": "US"
    }
  ]
}

In the second event, the player spun a slot machine ten times at 5,000 coins per spin. The value is the total coin cost (50,000) and sum_of_squares is 5000² x 10 = 250,000,000.

Success Response

Status Code

200

Response Body

JSON dictionary.

status

'ok'

results

An array of result objects, one for each event in the request. Each result contains status, user_id, and optionally errors.

summary

A summary object with total_events, successful_events, and failed_events counts.

Example

{
  "status": "ok",
  "results": [
    {
      "status": "ok",
      "user_id": "player_123"
    },
    {
      "status": "error",
      "user_id": "unknown_player",
      "errors": {"user_id": ["could not be found"]}
    }
  ],
  "summary": {
    "total_events": 2,
    "successful_events": 1,
    "failed_events": 1
  }
}

Individual event failures do not prevent other events in the batch from being processed. Check the results array to determine which events were processed successfully.

Error Responses

Bad Request

Status Code	400
Response Body	JSON dictionary with 'status' and 'errors' keys. 'status' will be 'error'. 'errors' will contain validation errors for the request.

Status Code

400

Response Body

JSON dictionary with 'status' and 'errors' keys. 'status' will be 'error'. 'errors' will contain validation errors for the request.

Example

{"status":"error","errors":{"events":["must be a non-empty array (max 100 items)"]}}

Rate Limit Response

Status Code	429
Response Body	JSON dictionary with 'status' and 'errors' keys. 'status' will be 'rate_limit'. 'errors' will contain the key 'rate_limit'

Status Code

429

Response Body

JSON dictionary with 'status' and 'errors' keys. 'status' will be 'rate_limit'. 'errors' will contain the key 'rate_limit'

Example

{"status":"rate_limit","errors":{"rate_limit":["/v2/analytics_events/batch may only be called 100 times per second. Please wait a second and try again"]}}