Agent Sessions

At a glance

You want to	Use	Where
Know when an API-started session is done	Poll its batch	REST API
Watch, redirect, approve, or answer a session from your editor	Ask your coding agent	MCP
Answer questions, approve a plan, or create a PR	The session view	Web app

Reference for AI: agent sessions at a glance

Interface	Tool / endpoint	What it does	Key constraint
REST API	`GET https://api.checksum.ai/public-api/v1/auto-generate/batch/{batchId}`	Status of the sessions in a generation batch	Read-only
REST API	`GET https://api.checksum.ai/public-api/v1/auto-heal/batch/{batchId}`	Status of the sessions in a healing batch	Read-only
MCP	`checksum_session_status`	Progress, latest agent messages, changed files, `prUrl`	Read-only
MCP	`checksum_session_list`	Lists recent agent sessions	Read-only
MCP	`checksum_session_prompt`	Sends a follow-up instruction into a session, or resumes a stopped one	Not cancelled sessions
MCP	`checksum_session_approve` / `checksum_session_answer`	Approves a deep-mode plan / answers pending questions	When `nextAction` is `approve` / `answer`
MCP	`checksum_session_stop` / `checksum_session_restart`	Pauses a session / restarts it as a new session	Restart returns a new session ID
MCP	`checksum_session_create_pr`	Opens the PR for a completed session without one	Synchronous; can take a minute or two
Web app	Agent Sessions page	Watch, answer questions, approve plans, create a PR	—

No session endpoints in REST: the public REST API can’t list sessions, answer questions, approve plans, or send prompts. Use MCP or the web app.
Batches group sessions: API-triggered generation and healing return a batchId. Poll until allTerminal is true.
Sessions clone the repositories, so they see only pushed commits.
Standard runs unattended; Deep pauses for plan approval.
Session statuses: Initializing, Cloning, Advancing, Running, Waiting for Input, Waiting for Approval, PR Eligible, Completed, Failed, Cancelled (see Session lifecycle).

Developer guide

Track sessions with the REST API and steer them over MCP

Track sessions from the REST API

When you start generation or healing through the API, you get back a batchId: a handle for one or more sessions working on your request. Check the batch every 10–30 seconds until allTerminal is true. Each session in the list shows its status and, once it’s done, a link to its pull request.

GET

curl https://api.checksum.ai/public-api/v1/auto-generate/batch/$BATCH_ID \
  -H "Authorization: Bearer $CHECKSUM_API_KEY"

Healing batches work the same way at GET https://api.checksum.ai/public-api/v1/auto-heal/batch/{batchId}. POST /auto-generate also returns links.session, a direct link to the session in the web app.

Sessions have no REST endpoints of their ownThe public REST API doesn’t have endpoints to list sessions, answer questions, approve plans, or send follow-up prompts. Use the web app or the MCP server for those.

Reference for AI: session batch endpoints

GET `https://api.checksum.ai/public-api/v1/auto-generate/batch/{batchId}`

Status of the sessions in a generation batch. Header: Authorization: Bearer $CHECKSUM_API_KEY. Path parameter batchId (string) from POST /public-api/v1/auto-generate. Full response fields: Generate Tests → Reference for AI.

curl https://api.checksum.ai/public-api/v1/auto-generate/batch/$BATCH_ID \
  -H "Authorization: Bearer $CHECKSUM_API_KEY"

GET `https://api.checksum.ai/public-api/v1/auto-heal/batch/{batchId}`

Status of the sessions in a healing batch. Header: Authorization: Bearer $CHECKSUM_API_KEY. Path parameter batchId (string) from POST /public-api/v1/auto-heal or an autoHeal run. Full response and batch status values: Auto-Healing → Poll healing progress.

curl https://api.checksum.ai/public-api/v1/auto-heal/batch/$BATCH_ID \
  -H "Authorization: Bearer $CHECKSUM_API_KEY"

Field used for session tracking	Type	Meaning
`allTerminal`	boolean	`true` when every session in the batch has finished; stop polling
`sessions[].sessionId`	string	Agent session ID
`sessions[].status`	string	That session’s state
`sessions[].prUrl`	string \| null	PR URL once opened
`links.session` (from `POST /auto-generate`)	string (URL)	Direct link to the session in the web app

Polling rule: every 10–30 seconds until allTerminal is true.Not available in REST: list sessions, answer questions, approve plans, send prompts.

Watch and steer sessions from your editor

With the Checksum MCP server connected, your coding agent can follow a session for you: it reports progress, the agent’s latest messages, the files it changed, and the PR it opened. You can also redirect a session that’s already running, just by asking:

Tell the Checksum session to also cover the "expired card" case.

That’s the same as typing into the session in the web app. Every result includes links into the web app, so you can open the session instead of copying IDs around. Your agent can also clear the pauses described in The session view without the web app: it approves a deep-mode plan with checksum_session_approve and answers questions with checksum_session_answer. It can stop or restart a session, and open the PR for a finished session that didn’t open one. See Deep mode and the approval loop.

Which sessions accept promptsRunning, waiting, paused, and completed sessions accept a prompt, and a prompt resumes a stopped session. A session that was cancelled, or failed without a way back, won’t accept one, and you’ll get an error saying so.

Reference for AI: MCP session tools

MCP server: https://api.checksum.ai/public-api/mcp.

Tool	Type	What it does
`checksum_session_status`	Read-only	Reports a run’s progress, the agent’s latest messages, the files it changed, the `prUrl` it opened, and `nextAction` (`approve`, `answer`, `prompt`, `wait`, `done`, `failed`). Poll by `batchId`, or by `sessionId` for detect and targeted-generate sessions.
`checksum_session_list`	Read-only	Lists recent agent sessions.
`checksum_session_prompt`	Changes things	Sends a follow-up instruction into a session. Equivalent to typing into the session in the web app. During plan approval it reopens planning; it doesn’t approve.
`checksum_session_approve`	Changes things	Approves the plan a deep-mode session is waiting on.
`checksum_session_answer`	Changes things	Answers pending questions: `answers` is one array of option labels per sub-question; optional `questionId`.
`checksum_session_stop`	Changes things	Pauses a session and keeps its workspace.
`checksum_session_restart`	Changes things	Restarts a stopped, failed, or finished session as a new session; poll `restartedAiAgentsSessionId` afterwards.
`checksum_session_create_pr`	Changes things	Opens the PR for a completed session; returns the existing `prUrl` if there is one.

Constraint: checksum_session_prompt fails with an error on a session that was cancelled or failed without a way back. Results include web-app links.

▦

In the Checksum web app

The session view, questions, and approvals

The session view

Open Agent Sessions in the web app to see every session in your project. Each one shows:

Status: the current lifecycle stage
Pipeline stages: which stages are done and which are next
Duration: how long the session has been running
Results: generated files and the PR link, once it completes

Answer the agent’s questions

When the session is Waiting for Input, the agent’s questions appear in the session view. Common ones:

“Which features should I focus on?”
“How does the login flow work for admin users?”
“Should I include negative test cases?”

Type your answers and submit. The agent picks up where it left off. Several questions may be waiting at once.

Give detailed answers. The more context the agent has, the better the results.

Approve plans at approval gates

When the session is Waiting for Approval, review what the agent produced, such as a plan or a set of detected flows. Click Approve to continue, or cancel if you want to adjust.

How it works

Session statuses, modes, and what starts a session

Session lifecycle

Initializing → Cloning → Advancing ⇄ Running → PR Eligible / Completed
                                     ↕                  ↘ Failed / Cancelled
                         Waiting for Input
                         Waiting for Approval

Agent Sessions list in the web app — The Agent Sessions page lists every session with its status and pipeline stage.

Status	What’s happening	What you do
Initializing	The agent’s environment is being set up. This usually takes a moment.	Nothing
Cloning	Your repositories are cloned and dependencies installed in the agent’s environment. The agent sees only pushed commits.	Nothing
Advancing	The pipeline is picking the next step. This happens between stages, e.g. after planning and before implementation.	Nothing
Running	The agent is working through a stage: planning, implementing, reviewing, or verifying, depending on the mode. Stages run in order.	Watch progress (optional)
Waiting for Input	The agent needs clarification. It may ask several questions at once.	Answer. The agent resumes automatically.
Waiting for Approval	A stage finished (e.g. a plan or a set of detected flows), and the agent is waiting before the next one.	Approve to continue, or cancel
PR Eligible	The work is done and file changes are ready, but no PR was opened automatically (e.g. a Slack or described-flow run with no PR context).	Review the changes and create a PR from the session view
Completed	Tests are generated or healed and committed, and a PR is open in your repository.	Review and merge the PR
Failed	Something went wrong: the application was unreachable, tests couldn’t be verified (persistent failures), or an unexpected error occurred.	Check the session details and try again
Cancelled	You stopped the session before it finished.	Nothing

A completed agent session showing pipeline stages and results — A completed session: pipeline stages, generated files, and the PR link.

Standard vs Deep sessions

How much interaction a session needs depends on its mode:

Standard is fully autonomous. The agent runs from start to finish without any input. You can start many sessions in parallel and come back to finished results.
Deep needs you for the first step (planning). The agent presents a plan and waits for your approval. After that, the remaining steps run on their own.

In practiceLaunch 10 Standard sessions and walk away. For Deep sessions, review and approve each plan, then leave them to finish.

What starts a session?

Each of these creates its own independent session:

Operation	Triggers
Detect	A collection’s Auto-detect test flows button (Detect Test Flows)
Generate	A flow’s Generate button · `/checksum generate` on a PR · auto-generate on PR open · `POST /auto-generate` · `@checksum` in Slack · `checksum_test_generate` over MCP · a finished recording in the Chrome extension (Generate Tests)
Heal	Automatic healing after a failing CI or scheduled run · `--cksm-auto-heal` · an `autoHeal` block on an execution request · `POST /auto-heal` · the GitHub Action’s `auto-heal: true` · agent actions in the Health Dashboard · `checksum_test_heal` over MCP (Auto-Healing)

Troubleshooting

The session failed during Cloning

Check that the Git integration is Active in Settings → Git Integration, and that the branch you referenced exists on the remote.

The session failed: application unreachable

Check the environment URL and test users in Environments. If the environment is behind a VPN or firewall, allowlist Checksum’s IPs (Security & Access).

The session has been Waiting for Input for a long time

Sessions don’t continue until you answer. Open the session and respond. From your coding agent, answer with checksum_session_answer (or approve a waiting plan with checksum_session_approve).

The session completed but there's no PR

The session is PR Eligible. Create the PR from the session view. This happens when the trigger had no pull-request context.

Deep vs Standard

Why some sessions ask for approval.

Generate Tests

Every way to start a generation session.

Auto-Healing

Healing sessions and batches.

Coding Agents & MCP

Steer sessions from your editor.

Start Here

Managing Your Project

Test Generation

Test Execution

Maintenance & Monitoring

Integrations

Security & Admin

At a glance

Track sessions from the REST API

GET `https://api.checksum.ai/public-api/v1/auto-generate/batch/{batchId}`

GET `https://api.checksum.ai/public-api/v1/auto-heal/batch/{batchId}`

Watch and steer sessions from your editor

The session view

Answer the agent’s questions

Approve plans at approval gates

Session lifecycle

Standard vs Deep sessions

What starts a session?

Troubleshooting

Deep vs Standard

Generate Tests

Auto-Healing

Coding Agents & MCP

​At a glance

​Track sessions from the REST API

​GET https://api.checksum.ai/public-api/v1/auto-generate/batch/{batchId}

​GET https://api.checksum.ai/public-api/v1/auto-heal/batch/{batchId}

​Watch and steer sessions from your editor

​The session view

​Answer the agent’s questions

​Approve plans at approval gates

​Session lifecycle

​Standard vs Deep sessions

​What starts a session?

​Troubleshooting

​Related

Deep vs Standard

Generate Tests

Auto-Healing

Coding Agents & MCP

At a glance

Track sessions from the REST API

GET `https://api.checksum.ai/public-api/v1/auto-generate/batch/{batchId}`

GET `https://api.checksum.ai/public-api/v1/auto-heal/batch/{batchId}`

Watch and steer sessions from your editor

The session view

Answer the agent’s questions

Approve plans at approval gates

Session lifecycle

Standard vs Deep sessions

What starts a session?

Troubleshooting

Related