Study ledger and events

curl https://app.userjourneys.ai/api/v1/studies/e5f6a7b8-1234-56cd-ef78-222222222222/ledger \
  -H "Authorization: Bearer uj_live_your_key_here"

const response = await fetch(
  "https://app.userjourneys.ai/api/v1/studies/e5f6a7b8-1234-56cd-ef78-222222222222/ledger",
  {
    headers: {
      Authorization: "Bearer uj_live_your_key_here",
    },
  }
);
const ledger = await response.json();
// ledger.questions[0].answers — answer patterns with graded evidence
// ledger.must_reads — the interviews worth reading, by rank

import requests

response = requests.get(
    "https://app.userjourneys.ai/api/v1/studies/e5f6a7b8-1234-56cd-ef78-222222222222/ledger",
    headers={"Authorization": "Bearer uj_live_your_key_here"},
)
ledger = response.json()

{
  "object": "study_ledger",
  "study_id": "e5f6a7b8-1234-56cd-ef78-222222222222",
  "version": 7,
  "updated_at": "2026-09-17T09:14:03.000Z",
  "phase": {
    "value": "collecting",
    "reason": "The last three interviews each added a new pattern to the onboarding question."
  },
  "questions": [
    {
      "object": "study_question",
      "id": "q_first_impression",
      "text": "What shapes the first impression of the product?",
      "source": "study:0",
      "status": "emerging",
      "note": null,
      "answers": [
        {
          "object": "study_item",
          "id": "a_setup_before_value",
          "kind": "answer",
          "question_id": "q_first_impression",
          "title": "Setup steps come before anything useful",
          "description": "Respondents describe connecting accounts and inviting teammates before seeing their own data.",
          "status": "active",
          "merged_into": null,
          "reason": null,
          "created_by_interview_id": "a1b2c3d4-5678-90ab-cdef-111111111111",
          "created_at": "2026-09-12T16:40:11.000Z",
          "supporters": 4,
          "weak": 1,
          "reviewed": 9,
          "evidence": [
            {
              "object": "study_evidence",
              "interview_id": "a1b2c3d4-5678-90ab-cdef-111111111111",
              "start": 61,
              "end": 68,
              "quote": "I had to connect three things before I saw a single chart.",
              "gloss": null,
              "grade": "A",
              "grade_reason": "Raised unprompted while describing the first session."
            },
            {
              "object": "study_evidence",
              "interview_id": "b2c3d4e5-6789-01bc-def0-222222222222",
              "start": 143,
              "end": 149,
              "quote": "Yeah, the invites, I guess that was a bit much.",
              "gloss": "Asked directly whether the setup felt long.",
              "grade": "D",
              "grade_reason": "Only agrees with the interviewer's framing."
            }
          ]
        }
      ]
    }
  ],
  "themes": [
    {
      "object": "study_item",
      "id": "t_pricing_page_confusion",
      "kind": "theme",
      "question_id": null,
      "title": "The pricing page is read as per-seat",
      "description": "Respondents say they expected to pay for each teammate they invited.",
      "status": "active",
      "merged_into": null,
      "reason": null,
      "created_by_interview_id": "c3d4e5f6-7890-12cd-ef01-333333333333",
      "created_at": "2026-09-15T10:02:47.000Z",
      "supporters": 3,
      "weak": 0,
      "reviewed": 9,
      "evidence": [
        {
          "object": "study_evidence",
          "interview_id": "c3d4e5f6-7890-12cd-ef01-333333333333",
          "start": 210,
          "end": 216,
          "quote": "I assumed every person I added would cost extra, so I stopped at two.",
          "gloss": null,
          "grade": "A",
          "grade_reason": "Concrete consequence the respondent brought up on their own."
        }
      ]
    }
  ],
  "must_reads": [
    {
      "interview_id": "c3d4e5f6-7890-12cd-ef01-333333333333",
      "rank": 1,
      "reason": "Walks through the whole first session and names the pricing assumption that stopped invites."
    }
  ],
  "excluded": [
    {
      "interview_id": "d4e5f6a7-8901-23de-f012-444444444444",
      "reason": "Respondent evaluated a competitor's product, not ours."
    }
  ],
  "notes": [
    {
      "id": "n_tenure_split",
      "kind": "observation",
      "text": "Respondents with an existing account skip the setup complaints entirely.",
      "created_at": "2026-09-16T08:30:00.000Z"
    }
  ],
  "preferences": [
    {
      "text": "Track whether respondents mention the mobile app at all.",
      "created_at": "2026-09-14T11:05:22.000Z"
    }
  ]
}

curl https://app.userjourneys.ai/api/v1/studies/e5f6a7b8-1234-56cd-ef78-222222222222/ledger \
  -H "Authorization: Bearer uj_live_your_key_here"

const response = await fetch(
  "https://app.userjourneys.ai/api/v1/studies/e5f6a7b8-1234-56cd-ef78-222222222222/ledger",
  {
    headers: {
      Authorization: "Bearer uj_live_your_key_here",
    },
  }
);
const ledger = await response.json();
// ledger.questions[0].answers — answer patterns with graded evidence
// ledger.must_reads — the interviews worth reading, by rank

import requests

response = requests.get(
    "https://app.userjourneys.ai/api/v1/studies/e5f6a7b8-1234-56cd-ef78-222222222222/ledger",
    headers={"Authorization": "Bearer uj_live_your_key_here"},
)
ledger = response.json()

{
  "object": "study_ledger",
  "study_id": "e5f6a7b8-1234-56cd-ef78-222222222222",
  "version": 7,
  "updated_at": "2026-09-17T09:14:03.000Z",
  "phase": {
    "value": "collecting",
    "reason": "The last three interviews each added a new pattern to the onboarding question."
  },
  "questions": [
    {
      "object": "study_question",
      "id": "q_first_impression",
      "text": "What shapes the first impression of the product?",
      "source": "study:0",
      "status": "emerging",
      "note": null,
      "answers": [
        {
          "object": "study_item",
          "id": "a_setup_before_value",
          "kind": "answer",
          "question_id": "q_first_impression",
          "title": "Setup steps come before anything useful",
          "description": "Respondents describe connecting accounts and inviting teammates before seeing their own data.",
          "status": "active",
          "merged_into": null,
          "reason": null,
          "created_by_interview_id": "a1b2c3d4-5678-90ab-cdef-111111111111",
          "created_at": "2026-09-12T16:40:11.000Z",
          "supporters": 4,
          "weak": 1,
          "reviewed": 9,
          "evidence": [
            {
              "object": "study_evidence",
              "interview_id": "a1b2c3d4-5678-90ab-cdef-111111111111",
              "start": 61,
              "end": 68,
              "quote": "I had to connect three things before I saw a single chart.",
              "gloss": null,
              "grade": "A",
              "grade_reason": "Raised unprompted while describing the first session."
            },
            {
              "object": "study_evidence",
              "interview_id": "b2c3d4e5-6789-01bc-def0-222222222222",
              "start": 143,
              "end": 149,
              "quote": "Yeah, the invites, I guess that was a bit much.",
              "gloss": "Asked directly whether the setup felt long.",
              "grade": "D",
              "grade_reason": "Only agrees with the interviewer's framing."
            }
          ]
        }
      ]
    }
  ],
  "themes": [
    {
      "object": "study_item",
      "id": "t_pricing_page_confusion",
      "kind": "theme",
      "question_id": null,
      "title": "The pricing page is read as per-seat",
      "description": "Respondents say they expected to pay for each teammate they invited.",
      "status": "active",
      "merged_into": null,
      "reason": null,
      "created_by_interview_id": "c3d4e5f6-7890-12cd-ef01-333333333333",
      "created_at": "2026-09-15T10:02:47.000Z",
      "supporters": 3,
      "weak": 0,
      "reviewed": 9,
      "evidence": [
        {
          "object": "study_evidence",
          "interview_id": "c3d4e5f6-7890-12cd-ef01-333333333333",
          "start": 210,
          "end": 216,
          "quote": "I assumed every person I added would cost extra, so I stopped at two.",
          "gloss": null,
          "grade": "A",
          "grade_reason": "Concrete consequence the respondent brought up on their own."
        }
      ]
    }
  ],
  "must_reads": [
    {
      "interview_id": "c3d4e5f6-7890-12cd-ef01-333333333333",
      "rank": 1,
      "reason": "Walks through the whole first session and names the pricing assumption that stopped invites."
    }
  ],
  "excluded": [
    {
      "interview_id": "d4e5f6a7-8901-23de-f012-444444444444",
      "reason": "Respondent evaluated a competitor's product, not ours."
    }
  ],
  "notes": [
    {
      "id": "n_tenure_split",
      "kind": "observation",
      "text": "Respondents with an existing account skip the setup complaints entirely.",
      "created_at": "2026-09-16T08:30:00.000Z"
    }
  ],
  "preferences": [
    {
      "text": "Track whether respondents mention the mobile app at all.",
      "created_at": "2026-09-14T11:05:22.000Z"
    }
  ]
}

Every study has a Study Manager: an agent that reads each quality interview in full and keeps one document, the ledger, describing what the study has learned. The ledger holds the questions the study is answering, the answer patterns and themes found so far, a graded quote from every interview that supports each of them, the interviews worth reading, and the agent’s call on where the study stands. The ledger is written only by the study’s agent. Every save creates a new version and records what changed as events. Both are read-only over the API: you read the ledger for the current picture and the events for the delta since you last looked.

GET /v1/studies/:id/themes remains the older automatic themes, regenerated from scratch after each interview. The ledger is the Study Manager’s account: versioned, graded, and counted the same way for every item.

`GET /v1/studies/:id/ledger`

Retrieve the current version of a study’s ledger.

Request

string

required

Bearer token. See Authentication.

string

required

Study ID (UUID).

string

"all" to include merged and retired items. Default: active items only.

curl https://app.userjourneys.ai/api/v1/studies/e5f6a7b8-1234-56cd-ef78-222222222222/ledger \
  -H "Authorization: Bearer uj_live_your_key_here"

const response = await fetch(
  "https://app.userjourneys.ai/api/v1/studies/e5f6a7b8-1234-56cd-ef78-222222222222/ledger",
  {
    headers: {
      Authorization: "Bearer uj_live_your_key_here",
    },
  }
);
const ledger = await response.json();
// ledger.questions[0].answers — answer patterns with graded evidence
// ledger.must_reads — the interviews worth reading, by rank

import requests

response = requests.get(
    "https://app.userjourneys.ai/api/v1/studies/e5f6a7b8-1234-56cd-ef78-222222222222/ledger",
    headers={"Authorization": "Bearer uj_live_your_key_here"},
)
ledger = response.json()

{
  "object": "study_ledger",
  "study_id": "e5f6a7b8-1234-56cd-ef78-222222222222",
  "version": 7,
  "updated_at": "2026-09-17T09:14:03.000Z",
  "phase": {
    "value": "collecting",
    "reason": "The last three interviews each added a new pattern to the onboarding question."
  },
  "questions": [
    {
      "object": "study_question",
      "id": "q_first_impression",
      "text": "What shapes the first impression of the product?",
      "source": "study:0",
      "status": "emerging",
      "note": null,
      "answers": [
        {
          "object": "study_item",
          "id": "a_setup_before_value",
          "kind": "answer",
          "question_id": "q_first_impression",
          "title": "Setup steps come before anything useful",
          "description": "Respondents describe connecting accounts and inviting teammates before seeing their own data.",
          "status": "active",
          "merged_into": null,
          "reason": null,
          "created_by_interview_id": "a1b2c3d4-5678-90ab-cdef-111111111111",
          "created_at": "2026-09-12T16:40:11.000Z",
          "supporters": 4,
          "weak": 1,
          "reviewed": 9,
          "evidence": [
            {
              "object": "study_evidence",
              "interview_id": "a1b2c3d4-5678-90ab-cdef-111111111111",
              "start": 61,
              "end": 68,
              "quote": "I had to connect three things before I saw a single chart.",
              "gloss": null,
              "grade": "A",
              "grade_reason": "Raised unprompted while describing the first session."
            },
            {
              "object": "study_evidence",
              "interview_id": "b2c3d4e5-6789-01bc-def0-222222222222",
              "start": 143,
              "end": 149,
              "quote": "Yeah, the invites, I guess that was a bit much.",
              "gloss": "Asked directly whether the setup felt long.",
              "grade": "D",
              "grade_reason": "Only agrees with the interviewer's framing."
            }
          ]
        }
      ]
    }
  ],
  "themes": [
    {
      "object": "study_item",
      "id": "t_pricing_page_confusion",
      "kind": "theme",
      "question_id": null,
      "title": "The pricing page is read as per-seat",
      "description": "Respondents say they expected to pay for each teammate they invited.",
      "status": "active",
      "merged_into": null,
      "reason": null,
      "created_by_interview_id": "c3d4e5f6-7890-12cd-ef01-333333333333",
      "created_at": "2026-09-15T10:02:47.000Z",
      "supporters": 3,
      "weak": 0,
      "reviewed": 9,
      "evidence": [
        {
          "object": "study_evidence",
          "interview_id": "c3d4e5f6-7890-12cd-ef01-333333333333",
          "start": 210,
          "end": 216,
          "quote": "I assumed every person I added would cost extra, so I stopped at two.",
          "gloss": null,
          "grade": "A",
          "grade_reason": "Concrete consequence the respondent brought up on their own."
        }
      ]
    }
  ],
  "must_reads": [
    {
      "interview_id": "c3d4e5f6-7890-12cd-ef01-333333333333",
      "rank": 1,
      "reason": "Walks through the whole first session and names the pricing assumption that stopped invites."
    }
  ],
  "excluded": [
    {
      "interview_id": "d4e5f6a7-8901-23de-f012-444444444444",
      "reason": "Respondent evaluated a competitor's product, not ours."
    }
  ],
  "notes": [
    {
      "id": "n_tenure_split",
      "kind": "observation",
      "text": "Respondents with an existing account skip the setup complaints entirely.",
      "created_at": "2026-09-16T08:30:00.000Z"
    }
  ],
  "preferences": [
    {
      "text": "Track whether respondents mention the mobile app at all.",
      "created_at": "2026-09-14T11:05:22.000Z"
    }
  ]
}

Before the study’s agent has saved its first version, the endpoint returns 404 with error.code "ledger_not_found":

404

{
  "error": {
    "type": "invalid_request_error",
    "code": "ledger_not_found",
    "message": "No ledger yet",
    "param": null
  }
}

Returns 404 with error.code "study_not_found" if the study doesn’t exist or doesn’t belong to your project.

`GET /v1/studies/:id/events`

List what changed in a study’s ledger, newest first. Each event is derived from the difference between two ledger versions; nothing is computed beside that diff.

Request

string

required

Bearer token. See Authentication.

string

required

Study ID (UUID).

string

Only events created at or after this ISO 8601 timestamp (inclusive), e.g. 2026-09-17T00:00:00Z. An event’s created_at can be passed back as is; URL-encode it, because a + in the offset otherwise decodes as a space.

string

Only events of this kind. Repeat the parameter for several kinds: ?kind=theme_created&kind=item_strengthened. See Event kinds.

integer

Number of events to return. Default 20, max 100.

string

Cursor for pagination. Pass the id of the last event from the previous page.

curl "https://app.userjourneys.ai/api/v1/studies/e5f6a7b8-1234-56cd-ef78-222222222222/events?since=2026-09-17T00:00:00Z" \
  -H "Authorization: Bearer uj_live_your_key_here"

const studyId = "e5f6a7b8-1234-56cd-ef78-222222222222";
const response = await fetch(
  `https://app.userjourneys.ai/api/v1/studies/${studyId}/events?since=2026-09-17T00:00:00Z`,
  {
    headers: {
      Authorization: "Bearer uj_live_your_key_here",
    },
  }
);
const { data, has_more } = await response.json();

import requests

study_id = "e5f6a7b8-1234-56cd-ef78-222222222222"
response = requests.get(
    f"https://app.userjourneys.ai/api/v1/studies/{study_id}/events",
    params={"since": "2026-09-17T00:00:00Z"},
    headers={"Authorization": "Bearer uj_live_your_key_here"},
)
data = response.json()["data"]

{
  "object": "list",
  "data": [
    {
      "object": "study_event",
      "id": "0f9b2c1e-4d3a-4b5c-8e6f-555555555555",
      "study_id": "e5f6a7b8-1234-56cd-ef78-222222222222",
      "ledger_version": 7,
      "kind": "item_strengthened",
      "item_id": "t_pricing_page_confusion",
      "interview_id": null,
      "detail": {
        "map": "themes",
        "from": 2,
        "to": 3,
        "threshold": 3
      },
      "created_at": "2026-09-17T09:14:03.000Z"
    },
    {
      "object": "study_event",
      "id": "1a8c3d2f-5e4b-4c6d-9f7a-666666666666",
      "study_id": "e5f6a7b8-1234-56cd-ef78-222222222222",
      "ledger_version": 7,
      "kind": "interview_reviewed",
      "item_id": null,
      "interview_id": "e5f6a7b8-9012-34ef-0123-555555555555",
      "detail": {
        "supports": 2,
        "weak": 0
      },
      "created_at": "2026-09-17T09:14:03.000Z"
    },
    {
      "object": "study_event",
      "id": "2b9d4e3a-6f5c-4d7e-af8b-777777777777",
      "study_id": "e5f6a7b8-1234-56cd-ef78-222222222222",
      "ledger_version": 6,
      "kind": "phase_changed",
      "item_id": null,
      "interview_id": null,
      "detail": {
        "from": null,
        "to": "collecting",
        "reason": "First three quality interviews reviewed; patterns still forming."
      },
      "created_at": "2026-09-16T08:30:00.000Z"
    }
  ],
  "has_more": false
}

Returns 404 with error.code "study_not_found" if the study doesn’t exist or doesn’t belong to your project. Before the first save the list is empty, not an error.

Errors

These two endpoints return a structured error body. type is "invalid_request_error" for 400 and 404 responses and "api_error" for 500. param names the query or path parameter the error is about, or is null.

400

{
  "error": {
    "type": "invalid_request_error",
    "code": "event_not_found",
    "message": "No such event: 0f9b2c1e-4d3a-4b5c-8e6f-555555555555",
    "param": "starting_after"
  }
}

Status	`code`	When
`400`	`invalid_parameter`	A parameter fails validation: a malformed `id`, an unknown `include` value, a `since` that is not an ISO 8601 timestamp, a `limit` outside 1–100, an unknown `kind`.
`400`	`event_not_found`	`starting_after` is not an event of this study.
`404`	`study_not_found`	The study doesn’t exist or doesn’t belong to your project.
`404`	`ledger_not_found`	The study’s agent has not saved a ledger yet.
`500`	`internal_error`	Something went wrong on our side.

Missing or invalid API keys return 401 with the shared error body.

Study ledger object

string

"study_ledger"

string

Study ID (UUID).

integer

The ledger version, starting at 1 on the agent’s first save and increasing by one per save. Events carry the version that produced them.

string

ISO 8601 timestamp of the save that produced this version.

object | null

The agent’s call on where the study stands, with its reason. null until the agent has made one.

Show properties

string

"collecting" (new interviews still add patterns or change question statuses), "saturated" (the last several interviews only strengthened what exists), or "answered" (the questions have stable, well-supported answers).

string

Why the agent made this call, in its own words.

study_question[]

The questions the study is answering, each with its answer patterns. The study’s configured questions come first in the study’s order, then questions derived from the research goal, then questions a person asked for. Answer patterns and themes are listed strongest first. See Study question.

study_item[]

Findings nobody asked for. See Study item.

object[]

The interviews worth reading, by rank. At most five.

Show properties

string

Interview ID (UUID). Retrieve it with GET /v1/interviews/:id.

integer

1 to 5; 1 is the first to read.

string

Why this interview earns its rank.

object[]

Interviews the agent set aside. An excluded interview has no evidence and is not counted.

Show properties

string

Interview ID (UUID).

string

Why it was excluded, for example an off-cohort or contaminated respondent.

object[]

Observations, caveats and method remarks that fit no item. Visible, never counted.

Show properties

string

Note ID, e.g. "n_tenure_split".

string

"observation", "caveat", or "method".

string

The note.

string

ISO 8601 timestamp.

object[]

What the study owner told the agent to track or drop, in chat. Preferences bind on every later turn.

Show properties

string

The preference as the agent recorded it.

string

ISO 8601 timestamp.

Study question

string

"study_question"

string

Question ID, e.g. "q_first_impression". Never reused.

string

The question as the agent phrased it. The agent derives its own list from the study’s goal and configured questions, and may split or rephrase them.

string

Where the question came from: "study:<n>" for the study’s configured question n (0-indexed), "goal" when derived from the research goal, or "user" when a person asked for it in chat.

string

"no_pattern" (no answer pattern yet), "emerging" (at least one pattern, counts still moving), or "answered" (patterns stable; the agent would defend the answer).

string | null

Free text about the question, e.g. "splits by tenure".

study_item[]

The answer patterns found for this question. Several per question is normal. See Study item.

Study item

An answer pattern or a theme. Both carry the same fields and the same counts.

string

"study_item"

string

Item ID: "a_…" for answers, "t_…" for themes. Never reused.

string

"answer" or "theme".

string | null

The question an answer belongs to. null for themes.

string

Names the pattern. Titles never state how many respondents; the counts do.

string

What respondents did or said.

string

"active" (counted and shown), "merged" (folded into merged_into), or "retired" (no longer tracked). Merged and retired items appear only with include=all.

string | null

The item this one was folded into, when status is "merged".

string | null

Why the item was merged or retired.

string | null

The interview that first surfaced the item.

string

ISO 8601 timestamp of the save that created the item.

integer

Interviews whose evidence for this item is graded A, B or C. This is the item’s number; see Grades and counts.

integer

Interviews whose evidence for this item is graded D or E. Not counted in supporters.

integer

Interviews the agent has reviewed and not excluded, in this ledger version. Read supporters against it: 4 of 9 reviewed.

study_evidence[]

One graded quote per supporting interview. See Study evidence.

Study evidence

string

"study_evidence"

string

Interview ID (UUID) the quote comes from.

number

Seconds into the interview where the quoted line starts.

number

Seconds into the interview where the quoted line ends. May equal start.

string

The respondent’s verbatim words, at most thirty words. Every quote is checked against the transcript before the ledger is saved.

string | null

Context the words alone would not carry, such as the interviewer’s question. Present when the grade depends on it.

string

"A" to "E". See Grades and counts.

string

One sentence, in the agent’s words, saying what earned the grade.

Grades and counts

Every piece of evidence is a graded quote. The grade says how much the respondent’s words earn for the item:

Grade	Meaning	Counted
`A`	The respondent raised it themselves and gave something concrete.	Yes
`B`	A direct, substantive answer to the interviewer’s question.	Yes
`C`	Supports the item but hedged, partial, or only meaningful with the gloss.	Yes
`D`	The words only mean this because of how the question was asked. The interviewer’s question is in the gloss.	No
`E`	A stretch.	No

An item’s supporters is the number of reviewed, non-excluded interviews with evidence graded A to C; weak is the number graded D or E. Both are counted over the same reviewed set, so supporters means the same thing for every item in a ledger. Excluded interviews contribute to neither. Titles and descriptions never state prevalence; compare supporters with reviewed instead.

Study event object

string

"study_event"

string

Event ID (UUID). Use it as starting_after to page.

string

Study ID (UUID).

integer

The ledger version whose save produced this event.

string

One of the event kinds.

string | null

The question, item or note the event is about, when there is one.

string | null

The interview the event is about, when there is one.

object

Small facts about the change. Keys depend on kind; see Event kinds. Never contains quotes.

string

ISO 8601 timestamp of the save that produced the event.

Event kinds

map in detail is "answers" or "themes", naming which kind of item the event is about.

`kind`	When	`item_id` / `interview_id`	`detail` keys
`question_created`	A new question.	question / —	`source`, `status`
`question_status_changed`	A question’s status changed.	question / —	`from`, `to`
`answer_created`	A new answer pattern.	item / —	`title`, `question`, `supporters`, `weak`, `reviewed`
`theme_created`	A new theme.	item / —	`title`, `supporters`, `weak`, `reviewed`
`item_merged`	An item’s status became `merged`.	item / —	`map`, `merged_into`, `reason`
`item_retired`	An item’s status became `retired`.	item / —	`map`, `reason`
`item_redefined`	An item’s title or description changed.	item / —	`map`, `fields` (the changed field names)
`item_strengthened`	An active item’s `supporters` crossed 3, 5, 10 or 20. One event per threshold crossed.	item / —	`map`, `from`, `to`, `threshold`
`interview_reviewed`	A new interview was reviewed.	— / interview	`supports`, `weak`
`stance_changed`	A reviewed interview’s set of supported items changed.	— / interview	`added`, `removed` (item ids)
`stance_regraded`	A piece of evidence was regraded.	item / interview	`interview`, `item`, `from`, `to` (grades)
`must_read_added`	An interview was made a must-read.	— / interview	`rank`, `reason`
`must_read_changed`	A must-read was re-ranked.	— / interview	`from_rank`, `to_rank`
`must_read_removed`	A must-read was dropped.	— / interview	`from_rank`
`interview_excluded`	An interview was excluded.	— / interview	`reason`
`note_added`	A note was added.	note / —	`kind`, `note_id`
`phase_changed`	The phase value changed. A reason-only edit is not an event.	— / —	`from`, `to`, `reason`

To watch a study, poll GET /v1/studies/:id/events?since=<last poll> and read the ledger when something you care about appears, for example theme_created or item_strengthened. Webhooks do not deliver study-level events in v1.

Getting Started

Interviews

React Native SDK

Integrations

AI Agent

Guides

API

Support

`GET /v1/studies/:id/ledger`

Request

`GET /v1/studies/:id/events`

Request

Errors

Study ledger object

Study question

Study item

Study evidence

Grades and counts

Study event object

Event kinds

​GET /v1/studies/:id/ledger

​Request

​GET /v1/studies/:id/events

​Request

​Errors

​Study ledger object

​Study question

​Study item

​Study evidence

​Grades and counts

​Study event object

​Event kinds

`GET /v1/studies/:id/ledger`

Request

`GET /v1/studies/:id/events`

Request

Errors

Study ledger object

Study question

Study item

Study evidence

Grades and counts

Study event object

Event kinds