Runs
Give an agent a job
The agent works on its own, outside this request, until it finishes the job or hits a limit, and answers right away with the run in progress. Follow it with GET /v2/runs/{id} or the run.* webhooks. With this scope the agent runs unattended any action it is granted, including the ones that write, as the person you declare in actor (or as your key when you declare none): your key is what vouches for them, nothing else is signed. The limits you ask for are cut to the server maximums (60 rounds and 120 minutes). If the agent has to ask something it pauses with status waiting_for_answer: answer it with POST /v2/runs/{id}/answer. Repeat the request with the same Idempotency-Key and you get the run already created, not a second one. Use dryRun=true to run the same checks (agent active and exposed, role of the actor, limits) and see the run as it would be created, without queueing anything.
Required scope: runs:write.
path Parameters
id^agt_[0-9A-Za-z]{22}… · requiredThe id of the agent (agt_…).
query Parameters
dryRunWhen true, the request goes through the same validation as the real one and is answered with what would happen (always 200), and nothing is saved, sent or charged. The answer has the same shape as the real one plus dryRun: true; an id in it is not saved. It does not use the Idempotency-Key.
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Idempotency-KeyMakes the request safe to retry. Once it starts running, its final response (2xx, 4xx or 5xx) is kept for 24 hours and the same key gets it back, without repeating the effect. A request rejected before it runs leaves the key free. A replayed create omits the secret. The same key with a different request is rejected with 409 idempotency_key_reused.
Give an agent a job › Request Body
goalWhat the agent has to achieve. It is treated as text from a user.
The person in your system the agent works for. It travels signed by Lelemon to every action and MCP server of the run as the actor, marked as declared by your key and not verified. Without it the run works as your key. A key cannot declare a role above its own.
Caps for this run. The server cuts them to its own maximums; what you leave out takes the default.
Give an agent a job › Responses
objectidagentIdstatusrunning: working, or in the queue. waiting_for_answer: paused to ask; question has it, answer it with POST /v2/runs/{id}/answer. completed_unverified: the agent says it finished and nobody has checked it, so do not read it as done. completed: a verifier checked it (it does not happen yet). stopped: the run was cut before the agent declared the job done, by a limit (rounds, time or the spending limit Lelemon sets for every run) or because the agent never concluded (no_conclusion) or repeated itself (loop); stopReason says which and result.partial keeps the last thing the agent wrote. failed: an error; result.error says what, or stopReason abandoned if nobody answered the pause in 30 days. canceled: you canceled it.
stopReasonWhy the run ended without finishing. Set with status stopped, and with status failed for abandoned. rounds: the run used all the rounds allowed by limits.maxRounds. cost: the run reached the spending limit Lelemon sets for every run. time: the run lasted all the minutes allowed by limits.maxMinutes. no_conclusion: the agent answered four times in a row without calling its finish action, so it never declared the job done. Its last answer is in result.partial. loop: the agent kept repeating the same action, so the run was cut. abandoned: with status failed: the agent asked a question and nobody answered it in 30 days.
questionWith status waiting_for_answer, what the agent asked. Answer it with POST /v2/runs/{id}/answer.
roundsRounds taken so far.
cancelRequestedtrue if a cancel was asked. While a worker runs it, the run stops at the start of its next round.
scheduleThe scheduled task that started this run. null for a run you created with POST /v2/agents/{id}/runs.
The person the run works for, as declared by the key that created it. null when the run works as the key itself.
createdAtstartedAtfinishedAtupdatedAtdryRunPresent and true when the request had dryRun=true.
List runs
The jobs given to agents, newest first. Filter by agentId, or by status=waiting_for_answer to build the queue of what waits for an answer. Read only and safe to repeat.
Required scope: runs:read.
query Parameters
limitcursorThe nextCursor of the previous page, with the same filters.
agentIdstatusscheduleIdOnly the runs started by this scheduled task.
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
List runs › Responses
Retrieve a run
Where the run is: its status, what it spent, the question it waits on, and what the agent declared when it finished. Read only and safe to repeat.
Required scope: runs:read.
path Parameters
id^run_[0-9A-Za-z]{22}… · requiredThe id of the run (run_…).
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Retrieve a run › Responses
objectidagentIdstatusrunning: working, or in the queue. waiting_for_answer: paused to ask; question has it, answer it with POST /v2/runs/{id}/answer. completed_unverified: the agent says it finished and nobody has checked it, so do not read it as done. completed: a verifier checked it (it does not happen yet). stopped: the run was cut before the agent declared the job done, by a limit (rounds, time or the spending limit Lelemon sets for every run) or because the agent never concluded (no_conclusion) or repeated itself (loop); stopReason says which and result.partial keeps the last thing the agent wrote. failed: an error; result.error says what, or stopReason abandoned if nobody answered the pause in 30 days. canceled: you canceled it.
stopReasonWhy the run ended without finishing. Set with status stopped, and with status failed for abandoned. rounds: the run used all the rounds allowed by limits.maxRounds. cost: the run reached the spending limit Lelemon sets for every run. time: the run lasted all the minutes allowed by limits.maxMinutes. no_conclusion: the agent answered four times in a row without calling its finish action, so it never declared the job done. Its last answer is in result.partial. loop: the agent kept repeating the same action, so the run was cut. abandoned: with status failed: the agent asked a question and nobody answered it in 30 days.
questionWith status waiting_for_answer, what the agent asked. Answer it with POST /v2/runs/{id}/answer.
roundsRounds taken so far.
cancelRequestedtrue if a cancel was asked. While a worker runs it, the run stops at the start of its next round.
scheduleThe scheduled task that started this run. null for a run you created with POST /v2/agents/{id}/runs.
The person the run works for, as declared by the key that created it. null when the run works as the key itself.
createdAtstartedAtfinishedAtupdatedAtCancel a run
If nobody is running it, it ends canceled now. If a worker is running it, cancelRequested turns true and it ends canceled when its next round starts: what it was doing finishes. A run that already ended answers 409 run_finished.
Required scope: runs:write.
path Parameters
id^run_[0-9A-Za-z]{22}… · requiredThe id of the run (run_…).
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Idempotency-KeyMakes the request safe to retry. Once it starts running, its final response (2xx, 4xx or 5xx) is kept for 24 hours and the same key gets it back, without repeating the effect. A request rejected before it runs leaves the key free. A replayed create omits the secret. The same key with a different request is rejected with 409 idempotency_key_reused.
Cancel a run › Responses
objectidagentIdstatusrunning: working, or in the queue. waiting_for_answer: paused to ask; question has it, answer it with POST /v2/runs/{id}/answer. completed_unverified: the agent says it finished and nobody has checked it, so do not read it as done. completed: a verifier checked it (it does not happen yet). stopped: the run was cut before the agent declared the job done, by a limit (rounds, time or the spending limit Lelemon sets for every run) or because the agent never concluded (no_conclusion) or repeated itself (loop); stopReason says which and result.partial keeps the last thing the agent wrote. failed: an error; result.error says what, or stopReason abandoned if nobody answered the pause in 30 days. canceled: you canceled it.
stopReasonWhy the run ended without finishing. Set with status stopped, and with status failed for abandoned. rounds: the run used all the rounds allowed by limits.maxRounds. cost: the run reached the spending limit Lelemon sets for every run. time: the run lasted all the minutes allowed by limits.maxMinutes. no_conclusion: the agent answered four times in a row without calling its finish action, so it never declared the job done. Its last answer is in result.partial. loop: the agent kept repeating the same action, so the run was cut. abandoned: with status failed: the agent asked a question and nobody answered it in 30 days.
questionWith status waiting_for_answer, what the agent asked. Answer it with POST /v2/runs/{id}/answer.
roundsRounds taken so far.
cancelRequestedtrue if a cancel was asked. While a worker runs it, the run stops at the start of its next round.
scheduleThe scheduled task that started this run. null for a run you created with POST /v2/agents/{id}/runs.
The person the run works for, as declared by the key that created it. null when the run works as the key itself.
createdAtstartedAtfinishedAtupdatedAtAnswer a run that asked something
The paused run resumes with your answer as context for its next round, and the agent sees who answered. Not idempotent: a question is answered once, and answering a run that is not paused answers 409 run_not_waiting.
Required scope: runs:write.
path Parameters
id^run_[0-9A-Za-z]{22}… · requiredThe id of the run (run_…).
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Idempotency-KeyMakes the request safe to retry. Once it starts running, its final response (2xx, 4xx or 5xx) is kept for 24 hours and the same key gets it back, without repeating the effect. A request rejected before it runs leaves the key free. A replayed create omits the secret. The same key with a different request is rejected with 409 idempotency_key_reused.
Answer a run that asked something › Request Body
answerThe answer to what the agent asked.
The person in your system who answered. Lelemon records it as declared by this key, not verified, and the agent sees who answered. Without it the answer comes from your key.
Answer a run that asked something › Responses
objectidagentIdstatusrunning: working, or in the queue. waiting_for_answer: paused to ask; question has it, answer it with POST /v2/runs/{id}/answer. completed_unverified: the agent says it finished and nobody has checked it, so do not read it as done. completed: a verifier checked it (it does not happen yet). stopped: the run was cut before the agent declared the job done, by a limit (rounds, time or the spending limit Lelemon sets for every run) or because the agent never concluded (no_conclusion) or repeated itself (loop); stopReason says which and result.partial keeps the last thing the agent wrote. failed: an error; result.error says what, or stopReason abandoned if nobody answered the pause in 30 days. canceled: you canceled it.
stopReasonWhy the run ended without finishing. Set with status stopped, and with status failed for abandoned. rounds: the run used all the rounds allowed by limits.maxRounds. cost: the run reached the spending limit Lelemon sets for every run. time: the run lasted all the minutes allowed by limits.maxMinutes. no_conclusion: the agent answered four times in a row without calling its finish action, so it never declared the job done. Its last answer is in result.partial. loop: the agent kept repeating the same action, so the run was cut. abandoned: with status failed: the agent asked a question and nobody answered it in 30 days.
questionWith status waiting_for_answer, what the agent asked. Answer it with POST /v2/runs/{id}/answer.
roundsRounds taken so far.
cancelRequestedtrue if a cancel was asked. While a worker runs it, the run stops at the start of its next round.
scheduleThe scheduled task that started this run. null for a run you created with POST /v2/agents/{id}/runs.
The person the run works for, as declared by the key that created it. null when the run works as the key itself.
createdAtstartedAtfinishedAtupdatedAt