Users
User endpoints provide access to user profiles derived from ingested events. Users are identified by their userId field on events -- there is no separate user creation endpoint. A user "exists" once at least one event with their user ID has been ingested.
All user endpoints require a private API key (Authorization: Bearer sk_...).
List Users
GET /v1/projects/:id/usersReturns a paginated list of unique users, ordered by most recently seen.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | number | 50 | Number of users to return (max 200) |
offset | number | 0 | Number of users to skip |
Example
curl "https://agentwallie.com/api/v1/projects/PROJECT_ID/users?limit=20&offset=0" \
-H "Authorization: Bearer sk_your_private_key"Response 200 OK
{
"data": [
{
"user_id": "user_abc123",
"last_seen": "2025-01-15T14:30:00.000Z",
"event_count": 142
},
{
"user_id": "user_def456",
"last_seen": "2025-01-15T12:15:00.000Z",
"event_count": 37
}
],
"pagination": {
"limit": 20,
"offset": 0,
"total": 1250
}
}Get User Detail
GET /v1/projects/:id/users/:uidReturns detailed information about a specific user, including their first and last seen timestamps, total event count, known device IDs, and distinct event types.
Example
curl https://agentwallie.com/api/v1/projects/PROJECT_ID/users/user_abc123 \
-H "Authorization: Bearer sk_your_private_key"Response 200 OK
{
"user_id": "user_abc123",
"device_ids": ["device_001", "device_002"],
"first_seen": "2025-01-01T08:00:00.000Z",
"last_seen": "2025-01-15T14:30:00.000Z",
"event_count": 142,
"event_types": [
"app_open",
"paywall_open",
"paywall_close",
"transaction_complete"
]
}Response Fields
| Field | Type | Description |
|---|---|---|
user_id | string | The user identifier |
device_ids | string[] | All distinct device IDs associated with this user |
first_seen | string | ISO timestamp of the user's earliest event |
last_seen | string | ISO timestamp of the user's most recent event |
event_count | number | Total number of events from this user |
event_types | string[] | Distinct event names the user has triggered |
Error 404
Returned when no events exist for the given user ID.
{
"error": "User not found. No events found for this user ID.",
"code": "USER_NOT_FOUND",
"suggestion": "List users with GET /v1/projects/:id/users. Users appear once events are ingested."
}Get User Event History
GET /v1/projects/:id/users/:uid/eventsReturns a paginated list of events for a specific user, ordered by most recent first.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | number | 50 | Number of events to return (max 200) |
offset | number | 0 | Number of events to skip |
Example
curl "https://agentwallie.com/api/v1/projects/PROJECT_ID/users/user_abc123/events?limit=10&offset=0" \
-H "Authorization: Bearer sk_your_private_key"Response 200 OK
{
"data": [
{
"id": "evt_001",
"event_name": "transaction_complete",
"timestamp": "2025-01-15T14:30:00.000Z",
"device_id": "device_001",
"properties": {
"product_id": "com.myapp.pro_monthly",
"transaction_amount": 9.99,
"currency": "USD"
},
"campaign_id": "camp_abc123",
"paywall_id": "pw_main"
},
{
"id": "evt_002",
"event_name": "paywall_open",
"timestamp": "2025-01-15T14:29:45.000Z",
"device_id": "device_001",
"properties": null,
"campaign_id": "camp_abc123",
"paywall_id": "pw_main"
}
],
"pagination": {
"limit": 10,
"offset": 0,
"total": 142
}
}Event Fields
| Field | Type | Description |
|---|---|---|
id | string | Unique event identifier |
event_name | string | Event type (e.g., app_open, paywall_open, transaction_complete) |
timestamp | string | ISO timestamp of when the event occurred |
device_id | string | null | Device identifier, if available |
properties | object | null | Parsed JSON properties attached to the event |
campaign_id | string | null | Associated campaign, if applicable |
paywall_id | string | null | Associated paywall, if applicable |