Skip to main content

​
What is the timeline?

The timeline is the ordered, immutable log of every event captured during a session. Events are ordered by timestamp. You can use it to see exactly what the candidate did, in what order — which prompts they sent, which files they changed, which commands they ran, and when they made architecture decisions.

​
Getting the timeline

GET /v1/sessions/:id/timeline Returns a paginated list of timeline events for a session.

​
Query parameters

​
limit
integer
default:"500"
Number of events to return per page. Maximum is 2000.
​
after
string
Event ID cursor for pagination. Pass the id of the last event from the previous page to fetch the next page.

​
Example request

curl "https://api.promptster.ai/v1/sessions/SESSION_ID/timeline?limit=100" \
  -H "Authorization: Bearer <your-token>"

​
Example response

{
  "events": [...],
  "hasMore": true
}

​
Event types

Each event has a kind field that identifies what it represents.
KindWhat it represents
promptA prompt submitted to the AI
ai_responseThe AI’s response
file_diffA file change (contains path, diff, lines added/removed)
file_createA new file created
commandA shell command run (contains command text and exit code)
test_runA test suite run (contains passed/failed/skipped counts)
git_actionA git operation (commit, branch, etc.)
decision_eventA captured architecture decision
session_startSession started
session_endSession ended (candidate ran promptster done)
checkpointA manual or automatic session checkpoint

​
Event envelope

Every event shares a common envelope:
​
id
string
Event UUID. Use this as the after cursor when paginating.
​
sessionId
string
The session this event belongs to.
​
kind
string
The event type. See the table above.
​
ts
string
ISO 8601 timestamp of when the event occurred.
​
data
object
Event-specific payload. Fields vary by kind — for example, a file_diff event includes path, diff, linesAdded, and linesRemoved; a command event includes command and exitCode.
​
provenance
object
Attribution metadata: { attribution, confidence, observability }. See below.

​
Provenance and attribution

The provenance object on each event describes how the change came to exist. The attribution field has the following values:
ValueMeaning
likely_aiChange almost certainly generated by the AI tool
ai_revised_by_humanAI output that the candidate manually edited
likely_humanChange made directly by the candidate
mixedAttribution is uncertain
system_generatedSystem event (CI, hooks)
Attribution is not a binary “AI wrote this / human wrote this” judgment. Promptster tracks provenance with confidence levels. A high likely_ai attribution with the candidate verifying and committing the result is normal and expected — prompting well is the work.

​
Paginating the timeline

For sessions with many events, paginate using the after cursor. 
# First page
curl "https://api.promptster.ai/v1/sessions/SESSION_ID/timeline?limit=500" \
  -H "Authorization: Bearer <your-token>"

# Next page (use the last event's id as 'after')
curl "https://api.promptster.ai/v1/sessions/SESSION_ID/timeline?limit=500&after=LAST_EVENT_ID" \
  -H "Authorization: Bearer <your-token>"
When hasMore is false, you have reached the end of the timeline.