Skip to main content
GET
/
v1
/
participants
/
{id}
/
activity
/
state-history
Get participant state history
curl --request GET \
  --url https://api.scrip.dev/v1/participants/{id}/activity/state-history \
  --header 'X-API-Key: <api-key>'
{
  "data": [
    {
      "changed_at": "2024-01-15T10:30:00Z",
      "changed_by_api_key_id": "550e8400-e29b-41d4-a716-446655440001",
      "event_id": "550e8400-e29b-41d4-a716-446655440002",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "key": "region",
      "new_value": "us-east",
      "old_value": "us-west",
      "operation": "set",
      "program_id": "550e8400-e29b-41d4-a716-446655440003",
      "rule_id": "550e8400-e29b-41d4-a716-446655440004",
      "state_type": "attribute"
    }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "YWJjMTIz"
  }
}
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
Use the state_type and key query parameters to filter results. Filter by state_type=tier and provide a program_id to isolate tier transitions. The from and to parameters filter on changed_at (when the state change was recorded). Use event_from / event_to to filter by the originating event’s event_timestamp instead — 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