Events

Submit telemetry events during gameplay. Events capture player actions, state changes, errors, and any other data you want to attach to bug reports for context.

Endpoint

POST /v1/ingest/events

Accepts a single event object or an array of up to 500 events.

Request body

Field	Type	Required	Description
`sessionId`	string (UUID)	Yes	Session to associate the event with
`buildId`	string (UUID)	No	Build to associate the event with
`eventType`	string	Yes	Event type identifier, e.g. `"player_action"`, `"error"`, `"checkpoint"`
`occurredAt`	string (ISO 8601)	No	When the event happened. Defaults to server time if omitted
`payload`	object	No	Arbitrary event data

Response

Returns an array of created events:

Field	Type	Description
`id`	string (UUID)	Event identifier
`sessionId`	string (UUID) or null	Associated session
`buildId`	string (UUID) or null	Associated build
`eventType`	string	Event type
`occurredAt`	string (ISO 8601)	Event timestamp
`payload`	object	Event data
`reportIds`	string[]	Bug reports this event is linked to
`overQuota`	boolean	`true` if the event exceeded your tenant’s monthly soft quota (still stored, but downgraded in the UI and excluded from paid features)

Examples

Single event

curl -X POST \
  -H "Authorization: Bearer flg_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "f47ac10b-...",
    "eventType": "player_action",
    "payload": {
      "action": "open_inventory",
      "scene": "Dungeon_Level_03",
      "position": { "x": 12.5, "y": 0.0, "z": -3.2 }
    }
  }' \
  https://ingest.forgelogger.dev/v1/ingest/events

Batch events

curl -X POST \
  -H "Authorization: Bearer flg_your_token" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "sessionId": "f47ac10b-...",
      "eventType": "checkpoint",
      "payload": { "name": "boss_room_entered" }
    },
    {
      "sessionId": "f47ac10b-...",
      "eventType": "error",
      "payload": { "message": "NullRef in EnemyAI.Update()", "stack": "..." }
    }
  ]' \
  https://ingest.forgelogger.dev/v1/ingest/events

Response

[
  {
    "id": "9a8b7c6d-...",
    "sessionId": "f47ac10b-...",
    "buildId": "7c9e6679-...",
    "eventType": "checkpoint",
    "occurredAt": "2026-04-08T14:35:00.000Z",
    "payload": { "name": "boss_room_entered" },
    "reportIds": [],
    "overQuota": false
  }
]

Node.js

// Send multiple events in one call
const events = [
  { sessionId, eventType: 'input', payload: { key: 'E', action: 'interact' } },
  { sessionId, eventType: 'state_change', payload: { health: 75, mana: 30 } },
];
 
const res = await fetch('https://ingest.forgelogger.dev/v1/ingest/events', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(events),
});

Common event types

These are suggestions — you can use any string as eventType:

Event type	Use case
`player_action`	Button presses, interactions, menu navigation
`state_change`	Health, inventory, quest progress updates
`checkpoint`	Level transitions, save points, boss encounters — put the name in `payload.name`
`crash`	The game crashed or hit an unrecoverable state
`error`	Runtime errors, exceptions, assertion failures
`performance`	FPS drops, memory spikes, load times
`network`	Connection changes, latency spikes

Two types have a meaning in demo feedback: when a player answers, the number of crash events of their session is frozen with the answer (so the dashboard can compare players who crashed with those who did not), and the payload.name of the session’s last checkpoint event is stored as the answer’s checkpoint when the game sent none. error events do not count as crashes.

Notes

Events are linked to bug reports either inline (via the events array in the report) or by referencing eventIds in the report submission.
Batch size is capped at 500 events per request.
If occurredAt is omitted, the server uses the current timestamp.
sessionId is required. Omitting it returns 400 and the event is not stored; a sessionId that does not reference an existing session for your project returns 404.