Run agents via API

A run is one unit of agent work started by your system: you send an instruction, the agent executes it, and the run carries the status and the result. This page walks through the full lifecycle — create, poll, collect, cancel.

Before you start

An API token with read_write mode, from Settings → API tokens (authentication).
The agent’s ID, visible on the agent page in the dashboard.

Create a run

Send the instruction in input.message. If the run is reacting to an event, put the event’s payload in input.data — the agent receives it as data, never as instructions.

curl -X POST https://app.leme.ai/api/v1/agents/AGENT_ID/runs \
  -H "Authorization: Bearer leme_pat_v1_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: lead-4821" \
  -d '{
    "input": {
      "message": "Qualify this lead and reply with a short summary.",
      "data": { "leadId": "4821", "source": "landing-page" }
    },
    "metadata": { "leadId": "4821" }
  }'

string

required

The instruction for the agent. Up to 128 KiB.

object

Free-form JSON with event data, up to 128 KiB. Framed as untrusted data for the agent — use it for payloads coming from the outside world.

object

Up to 16 string keys (values up to 512 characters). Echoed back on the run and in webhooks — use it to correlate with records in your system.

string

Continue an existing API session of this agent instead of starting a new conversation. Runs on the same session are processed in order.

string

HTTPS URL notified when the run finishes. See Completion webhooks.

string

Optional title for the new session, shown in the dashboard.

The response is 202 Accepted with the run resource:

{
  "id": "run_id",
  "object": "agent.run",
  "agentId": "agent_id",
  "sessionId": "session_id",
  "status": "queued",
  "statusDetail": null,
  "origin": "api",
  "input": { "message": "Qualify this lead and reply with a short summary." },
  "output": null,
  "error": null,
  "metadata": { "leadId": "4821" },
  "createdAt": 1720000000000,
  "completedAt": null,
  "urls": { "self": "/api/v1/runs/run_id" }
}

Always send an Idempotency-Key. If your request is retried, you get the original run back instead of a duplicate. Details in the API overview.

Follow the run

Poll the URL from urls.self until the status is terminal:

curl https://app.leme.ai/api/v1/runs/RUN_ID \
  -H "Authorization: Bearer leme_pat_v1_..."

Status	Meaning	Terminal
`queued`	Waiting to start	No
`in_progress`	The agent is working. `statusDetail: "delegated"` means it handed work to a longer-running process	No
`waiting_approval`	Paused for a human approval in the dashboard	No
`completed`	Done — `output.text` has the agent’s answer	Yes
`failed`	Something went wrong — see `error.code` and `error.message`	Yes
`canceled`	Canceled before it started	Yes

Non-terminal responses include a retry-after header with a suggested polling interval. When the run completes:

{
  "id": "run_id",
  "status": "completed",
  "output": { "text": "High-priority lead: decision maker at a 200-person company..." },
  "completedAt": 1720000042000
}

A run in waiting_approval resumes after someone approves the pending action in the dashboard. If you registered a callbackUrl, you also receive a run.waiting_approval event at that moment — useful to alert the approver.

Prefer not to poll? Register a callbackUrl and receive a signed webhook on completion — see Completion webhooks.

List runs

curl "https://app.leme.ai/api/v1/agents/AGENT_ID/runs?limit=20" \
  -H "Authorization: Bearer leme_pat_v1_..."

Returns { "runs": [...], "nextCursor": "..." }, newest first. Pass cursor to fetch the next page and status to filter (for example status=failed).

Cancel a run

curl -X POST https://app.leme.ai/api/v1/runs/RUN_ID/cancel \
  -H "Authorization: Bearer leme_pat_v1_..."

Only runs still in queued can be canceled. A run already executing returns 409 not_cancellable; canceling an already-finished run is harmless and returns the resource unchanged.

Continue a conversation

Each run without a sessionId starts a fresh session. To keep context across runs — a back-and-forth with the same agent — reuse the sessionId returned by the first run:

curl -X POST https://app.leme.ai/api/v1/agents/AGENT_ID/runs \
  -H "Authorization: Bearer leme_pat_v1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "SESSION_ID",
    "input": { "message": "Now draft a follow-up email for that lead." }
  }'

The session appears in the dashboard like any other conversation, so your team can read it and pick it up at any time.

Get Started

Agents

Tools & permissions

Automation

Artifacts

Workspace

API

Run agents via API

Before you start

Create a run

Follow the run

List runs

Cancel a run

Continue a conversation

​Before you start

​Create a run

​Follow the run

​List runs

​Cancel a run

​Continue a conversation

Before you start

Create a run

Follow the run

List runs

Cancel a run

Continue a conversation