Payloads

Fields on every lab event

Field	Always?	Type	Description
type	✓	string	The event type, for example lab.session_ready
session_id	✓	string	The lab session. The same id appears on the session’s sandbox events, so every event in a session joins on this field
team_id	✓	string	The Instruqt team the session belongs to
user_id	✓	string	The user running the session
lab_id	✓	string	The lab being run
timestamp	✓	string	RFC 3339. When Instruqt received the event, not when the transition happened. Do not compute durations from it
hot_start	✓	boolean	Whether the sandbox came from a pre-provisioned pool. A session with hot_start set to true sends no sandbox provisioning events
lab_slug		string	The lab’s URL identifier. Left out when the lab’s slug cannot be resolved
user_type		string	How the actor is classified: instruqt, member, developer, external, or platform. Fixed at session start and not updated afterwards
mode		string	Where the session runs: embed or platform. Self-reported by the client, so descriptive only — never use it for billing or as a trust signal
invite_id		string	The invite the session came from, if any. Matches invite_id on invite.claimed
custom_parameters		object	Your own runtime parameters for this session, forwarded as key/value strings. Left out when there are none

Fields on specific lifecycle events

Event	Adds	Notes
lab.session_stopped	reason	string, optional. Why the session ended: user, idle, or expired
lab.session_failed	error	string, optional. Human-readable detail, for diagnostics rather than branching
lab.sandbox_failed	error, error_type	Both string, both optional. See the error_type glossary
lab.sandbox_provisioned	cpus, memory	Both number. The sandbox’s vCPU count, and its memory in megabytes

Fields on progress events

Field	On	Always?	Type	Description
chapter_id	All progress events	✓	string	The chapter, stable across sessions of the same lab version
page_id	Page, task, and quiz events	✓	string	The page, stable across sessions of the same lab version
activity_id	Task and quiz events	✓	string	The task or quiz, as addressed in the lab definition
activity_type	Task and quiz events	✓	string	task or quiz — which kind of activity activity_id names
chapter_index	All progress events		number	Position of the chapter in the lab, starting at 1
total_chapters	All progress events		number	How many chapters the lab has
chapter_title	All progress events		string	The chapter’s title, as its author wrote it
page_index	Page, task, and quiz events		number	Position of the page within its chapter, starting at 1
total_pages	Page, task, and quiz events		number	How many pages that chapter has
page_title	Page, task, and quiz events		string	The page’s title, as its author wrote it
activity_index	Task and quiz events		number	Position of the activity among all the lab’s activities, counting tasks and quizzes together, starting at 1
total_activities	Task and quiz events		number	How many activities the lab has in total, tasks and quizzes together

error_type glossary

Value	Meaning
sandbox_error_type_creation_failed	The sandbox itself could not be created or started — its compute, cloud accounts, or secrets. This value does not separate an Instruqt infrastructure fault from a lab configuration that cannot produce a working sandbox, so read error rather than branching on it
sandbox_error_type_parsing_failed	The lab’s configuration could not be parsed
sandbox_error_type_initialization_failed	The sandbox was created but could not be initialised
sandbox_error_type_resource_creation_failed	A resource inside the sandbox — a container, a VM, a Terraform run — failed to be created
sandbox_error_type_download_failed	Something the sandbox had to download could not be fetched
sandbox_error_type_resource_destruction_failed	A resource inside the sandbox failed to be torn down
sandbox_error_type_unspecified	The failure was not classified

invite.claimed payload

Field	Always?	Type	Description
type	✓	string	invite.claimed
invite_id	✓	string	The invite that was claimed
claim_id	✓	string	This particular claim of the invite
user_id	✓	string	The user who claimed it
team_id	✓	string	The team the invite belongs to
team_slug	✓	string	That team’s URL identifier
timestamp	✓	string	RFC 3339
custom_parameters		object	The invite’s custom parameters. Left out when there are none

Sessions that send no events at all

• Draft and workspace sessions
• Automated lab test runs

Examples

lab.session_ready

{
  "type": "lab.session_ready",
  "session_id": "cs-8f2a41d0",
  "team_id": "instruqt-demo",
  "user_id": "u-91ab77",
  "user_type": "external",
  "lab_id": "6b1f0c2e-4a77-4c19-9b3e-2d51aa0f7c88",
  "lab_slug": "kubernetes-basics",
  "mode": "platform",
  "invite_id": "inv-4c81ab",
  "custom_parameters": { "cohort": "spring-2026" },
  "hot_start": false,
  "timestamp": "2026-08-25T09:14:03Z"
}

lab.sandbox_provisioned

{
  "type": "lab.sandbox_provisioned",
  "session_id": "cs-8f2a41d0",
  "team_id": "instruqt-demo",
  "user_id": "u-91ab77",
  "lab_id": "6b1f0c2e-4a77-4c19-9b3e-2d51aa0f7c88",
  "lab_slug": "kubernetes-basics",
  "cpus": 4,
  "memory": 8192,
  "hot_start": false,
  "timestamp": "2026-08-25T09:13:58Z"
}

lab.sandbox_failed

{
  "type": "lab.sandbox_failed",
  "session_id": "cs-3b7e0c11",
  "team_id": "instruqt-demo",
  "user_id": "u-91ab77",
  "lab_id": "6b1f0c2e-4a77-4c19-9b3e-2d51aa0f7c88",
  "lab_slug": "kubernetes-basics",
  "error": "sandbox creation timed out",
  "error_type": "sandbox_error_type_creation_failed",
  "hot_start": false,
  "timestamp": "2026-08-25T09:16:22Z"
}

lab.task_completed

{
  "type": "lab.task_completed",
  "session_id": "cs-8f2a41d0",
  "team_id": "instruqt-demo",
  "user_id": "u-91ab77",
  "lab_id": "6b1f0c2e-4a77-4c19-9b3e-2d51aa0f7c88",
  "lab_slug": "kubernetes-basics",
  "activity_id": "resource.task.deploy_the_app",
  "activity_type": "task",
  "activity_index": 3,
  "total_activities": 12,
  "page_id": "deploy-the-app",
  "page_index": 2,
  "total_pages": 4,
  "page_title": "Deploy the app",
  "chapter_id": "introduction",
  "chapter_index": 1,
  "total_chapters": 3,
  "chapter_title": "Introduction",
  "hot_start": false,
  "timestamp": "2026-08-25T09:22:41Z"
}

lab.session_completed

{
  "type": "lab.session_completed",
  "session_id": "cs-8f2a41d0",
  "team_id": "instruqt-demo",
  "user_id": "u-91ab77",
  "lab_id": "6b1f0c2e-4a77-4c19-9b3e-2d51aa0f7c88",
  "lab_slug": "kubernetes-basics",
  "hot_start": false,
  "timestamp": "2026-08-25T09:41:07Z"
}

invite.claimed

{
  "type": "invite.claimed",
  "invite_id": "inv-4c81ab",
  "claim_id": "clm-77d0e2",
  "user_id": "u-91ab77",
  "team_id": "instruqt-demo",
  "team_slug": "instruqt-demo",
  "custom_parameters": { "cohort": "spring-2026" },
  "timestamp": "2026-08-25T09:13:44Z"
}