Start a stateful Research Agent session. Elicit investigates the query asynchronously, reports its activity as structured events, and may produce downloadable artifacts.

The response returns immediately with a sessionId. Use the events endpoint to follow the research, then send messages to refine or continue it. The session is also available at the returned url.

Project context

Optionally pass projectId to start inside an existing project you own. Find one with GET /api/v2/projects, or create one first with POST /api/v2/projects and a body such as {"name":"GLP-1 safety review","goal":"Compare cardiovascular outcomes"}. Then pass the returned id to this endpoint. MCP supports the same workflow with list_projects, create_project, and create_agent_session.

The session becomes a project item before its first turn starts, and the agent receives the project context from the initial query. The response includes projectId. Shared projects are not supported, even with writer access. A missing, removed, deleted, or non-owned project returns 400 invalid_request before creating a session or charging workflow quota. Omission preserves standalone creation. Creating a project is a separate operation; a failed session creation leaves the project available to reuse.

Research depth

Optionally set researchDepth to fastest, fast, balanced, smart, or smartest when creating a session (also supported by MCP's create_agent_session). Omission preserves the existing account/model default. The selected preset is applied through the same server-side configuration and entitlement checks as the web interface. Plan and contract limits still apply: unavailable depths are reduced to the allowed ceiling, so smartest becomes smart on Pro, and Enterprise accounts without higher-depth access are limited to balanced. custom and arbitrary model configuration are not supported. This option is only available at creation, not on follow-up messages.

End-to-end workflow

A full research task may involve several requests against a single session. To drive it end to end:

1. (Optional) Upload files. POST /api/v2/files, PUT the bytes to the presigned URL, and keep each file_id (see the Upload endpoint).
2. Create the session. POST /api/v2/sessions/agents with your query and any attachments. The response is immediate with status: "processing" and a sessionId.
3. Poll for activity. GET /api/v2/sessions/agents/:sessionId/events. Pass the returned cursor unchanged on each subsequent poll to receive immutable event occurrences not observed at that checkpoint. Append them in response order and deduplicate retries by eventId. Poll every 3–10 seconds while the top-level status is processing.
4. Detect idle. The agent is ready for another request when a session_idle event appears and the top-level status returns to completed. For a Research Agent session, completed means idle and awaiting input — not that the session is permanently closed. Watch for these events along the way:
   • question — the agent needs input; answer it with a follow-up message.
   • error — the agent encountered an error; retryable indicates whether resending is worthwhile.
   • session_paused — the account hit its usage limit; the status becomes pausedForInsufficientQuota. Resolve the limit, then resume the session via POST /api/v2/sessions/:sessionId/resume (or the Elicit web interface) before continuing.
5. Send a follow-up. POST /api/v2/sessions/agents/:sessionId/messages with your message (and any attachments). Correlate the returned messageId with the matching user_message event, then return to step 3.
6. Retrieve artifacts. GET /api/v2/sessions/agents/:sessionId/artifacts to list what the agent produced: files appear under artifacts (GET .../artifacts/:artifactId/download for a short-lived presigned download URL — treat it as a credential), and interactive outputs (tables, prose, presentations, figures) appear under deliveredOutputs (GET .../artifacts/:artifactId/content for their contents).
7. Retrieve cited sources. GET /api/v2/sessions/agents/:sessionId/sources for every source the session cited, listed once each with its abstract. Join it to the citations on the events feed by sourceRef.
8. (Optional) Stop early. POST /api/v2/sessions/agents/:sessionId/stop to interrupt a running turn, then poll the events endpoint for the session_stopped event.

Session status

The list, detail, and events endpoints all report the same top-level status:

• processing — the agent is working (or the session has not started yet).
• completed — idle and awaiting input; the latest work finished successfully.
• failed — the latest work ended with an error.
• pausedForInsufficientQuota — paused at the account usage limit; resume once the limit clears.

The shared session-status schema also includes unknown for legacy reports and systematic reviews. Agent endpoints return the four statuses above: when no execution outcome is available and the session is not quota-paused, they report processing rather than unknown.

Application errors use the standard { "error": { "code", "message" } } envelope. The edge rate limit's 429 response is the flat format described under Error Handling.

Example

# Minimal
curl -X POST https://elicit.com/api/v2/sessions/agents \
  -H "Authorization: Bearer elk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"query":"What are the effects of GLP-1 receptor agonists on cardiovascular outcomes?"}'

# Start inside an owned project
curl -X POST https://elicit.com/api/v2/sessions/agents \
  -H "Authorization: Bearer elk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"query":"Compare the latest trials.","projectId":"9c1f6a7e-5d24-4a3b-9f0e-1b2c3d4e5f60"}'

# Select a research depth
curl -X POST https://elicit.com/api/v2/sessions/agents \
  -H "Authorization: Bearer elk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"query":"Compare randomized trials of GLP-1 receptor agonists.","researchDepth":"smart"}'

# With an uploaded file attached to the initial turn
curl -X POST https://elicit.com/api/v2/sessions/agents \
  -H "Authorization: Bearer elk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"query":"Summarize the attached trial and compare it to the current literature.","attachments":[{"file_id":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"}]}'

{
  "query": "What are the effects of GLP-1 receptor agonists on cardiovascular outcomes?",
  "attachments": [
    {
      "file_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
    }
  ],
  "projectId": "9c1f6a7e-5d24-4a3b-9f0e-1b2c3d4e5f60",
  "researchDepth": "smart"
}

{
  "sessionId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "url": "https://elicit.com/agent/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
}