---
title: "Send a message to a Research Agent session"
method: POST
path: "/sessions/agents/{sessionId}/messages"
tags: ["Research Agent"]
---

# Send a message to a Research Agent session

`POST /sessions/agents/{sessionId}/messages`

Insert a follow-up message and start another asynchronous turn. Use messages to refine a result, answer the agent, redirect the research, or request another artifact.

The response includes a `messageId`. The corresponding `user_message` event carries the same value, allowing the client to confirm delivery.

Attach previously uploaded files by including their `file_id`s in the `attachments` array (see the Upload endpoint).

If the session is paused for insufficient quota, resolve the usage limit and resume it via `POST /api/v2/sessions/:sessionId/resume` (or the Elicit web interface) before sending another message.

### Example

```bash
curl -X POST https://elicit.com/api/v2/sessions/agents/{sessionId}/messages \
  -H "Authorization: Bearer elk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"message":"Focus on randomized controlled trials only."}'
```

## Path parameters

- `sessionId` string, uuid, required

## Request body

- object
  - `message` string, required — The message to insert into the running research agent session.
  - `attachments` object[] — Files to attach to this turn, each referencing a file_id from POST /api/v2/files. Attached files are made available to the research agent exactly as uploads made in the web interface are.
    - `file_id` string, uuid, required — The file_id returned by POST /api/v2/files for a previously uploaded file.

## Response `202`

Message accepted. The session is processing another turn.

- PostAgentSessionMessageResponse
  - `sessionId` string, required — Unique identifier for the research agent session.
  - `status` 'processing', required — The session is processing the inserted message.
  - `messageId` string, required — Identifier of the inserted message. Correlate it with the messageId on the matching user_message event.
  - `url` string, required — URL to view and continue the session in the Elicit web interface.

## Other responses

- `400` — Invalid request. `message` must contain 1–2,000 characters.
- `401` — Authentication failed. The API key is missing, invalid, revoked, or expired.
- `402` — Insufficient quota.
- `403` — API access is not available on your current plan. Upgrade to Pro or above to use the API.
- `404` — The Research Agent API is not enabled for this account, or the session does not exist or belongs to another user.
- `409` — The session failed or is paused for insufficient quota and cannot accept a message.
- `429` — Rate limit exceeded. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.
- `500` — An unexpected error occurred. Retry after a short delay.

---

[API](https://skmtc.dev/elicit/apis/elicit-api.md) · [All operations](https://skmtc.dev/elicit/apis/elicit-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/elicit/elicit-api/revisions/2b42624536e5/schema)