Skip to main content
GET
Get participant state history
Returns a unified timeline of state changes for a participant, including tags, counters, attributes, and tiers. Each entry includes:
  • state_type: what changed (tag, attribute, counter, or tier)
  • key: the specific key that was modified
  • operation: set or delete
  • old_value / new_value: the value before and after the change
  • event_id: present when the change was triggered by a rule during event processing
  • changed_by_api_key_id: present when the change was made via a direct API call
Filter by state_type and key to narrow results. Use state_type=tier with a program_id to isolate tier transitions. Filter by from / to on changed_at (when the state change was recorded), or by event_from / event_to on the originating event’s event_timestamp. Entries without an event fall back to their changed_at. Both pairs can be used simultaneously (AND semantics).
For usage patterns and examples, see the Participants guide.

Authorizations

X-API-Key
string
header
required

API key passed in the X-API-Key header.

Path Parameters

id
string<uuid>
required

Participant ID

Query Parameters

state_type
enum<string>

Filter by state type

Available options:
tag,
counter,
attribute,
tier
key
string

Filter by key

program_id
string<uuid>

Filter by program ID (for tier entries)

operation
enum<string>

Filter by operation

Available options:
set,
delete,
add,
remove,
auto_reset
from
string<date-time>

Start of time window (RFC 3339) — filters on system ingestion time

to
string<date-time>

End of time window (RFC 3339) — filters on system ingestion time

event_from
string<date-time>

Start of event occurrence window (RFC 3339) — filters on event_timestamp

event_to
string<date-time>

End of event occurrence window (RFC 3339) — filters on event_timestamp

limit
integer

Maximum results (default 50, max 100)

Required range: x >= 1
cursor
string

Pagination cursor from previous response

Response

State history entries

data
object[]

Data contains the list of items

pagination
object

Pagination contains cursor information for fetching more results