Get User Timeline

GET /v1/user-journeys/users/{externalId}/timeline

Returns a paginated list of all events for a user, ordered by most recent first. Includes game plays, campaign events, points, and custom events.

Authentication

Header	Required	Value
X-API-Key	Yes	Your public key

Path Parameters

Parameter	Type	Required	Description
externalId	string	Yes	The user’s external ID

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	20	Items per page (max 100)

Request Examples

cURL

curl "https://api.gamifyhost.com/v1/user-journeys/users/user_12345/timeline?page=1&limit=10" \
  -H "X-API-Key: pk_live_your_public_key"

JavaScript

const response = await fetch(
  'https://api.gamifyhost.com/v1/user-journeys/users/user_12345/timeline?page=1&limit=10',
  {
    headers: { 'X-API-Key': 'pk_live_your_public_key' },
  }
);

const { data } = await response.json();
data.events.forEach(event => {
  console.log(`[${event.category}] ${event.eventType} — ${event.occurredAt}`);
  if (event.points > 0) console.log(`  +${event.points} pts`);
});
console.log(`Page ${data.page}, ${data.total} total events`);

Python

import requests

response = requests.get(
    "https://api.gamifyhost.com/v1/user-journeys/users/user_12345/timeline",
    headers={"X-API-Key": "pk_live_your_public_key"},
    params={"page": 1, "limit": 10},
)

data = response.json()["data"]
for event in data["events"]:
    print(f"[{event['category']}] {event['eventType']} — {event['occurredAt']}")
print(f"Total: {data['total']} events")

Response

Status: 200 OK

{
  "status": "success",
  "data": {
    "events": [
      {
        "id": "e1f2a3b4-c5d6-7890-abcd-ef1234567890",
        "partnerId": "partner-uuid",
        "externalId": "user_12345",
        "environment": "LIVE",
        "category": "GAME_PLAY",
        "eventType": "spin_the_wheel",
        "sourceId": "gpr_abc123",
        "points": 50,
        "reference": "game_play_gpr_abc123",
        "metadata": {
          "gameType": "spin_the_wheel",
          "rewardValue": 50,
          "outcome": "cashback"
        },
        "occurredAt": "2025-03-05T14:22:00Z"
      },
      {
        "id": "a2b3c4d5-e6f7-8901-bcde-f12345678901",
        "partnerId": "partner-uuid",
        "externalId": "user_12345",
        "environment": "LIVE",
        "category": "CAMPAIGN",
        "eventType": "purchase",
        "sourceId": "campaign-uuid",
        "points": 100,
        "reference": "campaign_xxx_user_12345_1709654520",
        "metadata": {},
        "occurredAt": "2025-03-05T13:42:00Z"
      },
      {
        "id": "b3c4d5e6-f7a8-9012-cdef-123456789012",
        "partnerId": "partner-uuid",
        "externalId": "user_12345",
        "environment": "LIVE",
        "category": "CUSTOM",
        "eventType": "product_viewed",
        "sourceId": "",
        "points": 0,
        "reference": "",
        "metadata": {
          "productId": "prod_abc",
          "productName": "Premium Plan"
        },
        "occurredAt": "2025-03-05T13:30:00Z"
      }
    ],
    "total": 128,
    "page": 1,
    "limit": 10
  }
}

Event Fields

Field	Type	Description
id	string	Unique event ID
externalId	string	The user’s external ID
category	string	Event category (GAME_PLAY, CAMPAIGN, POINTS, CUSTOM, PAGE_VIEW, SESSION)
eventType	string	Specific event type
sourceId	string	Reference to the source (game play record ID, campaign ID, etc.)
points	integer	Points associated with this event
reference	string	Idempotency/deduplication key
metadata	object	Arbitrary event data
occurredAt	string	When the event occurred (ISO 8601)

Pagination Fields

Field	Type	Description
total	integer	Total number of events for this user
page	integer	Current page number
limit	integer	Items per page

Errors

Code	Message
500	Failed to fetch timeline