API: Executions

Endpoints for listing, triggering, and inspecting bot executions.

List Executions

GET /api/v1/bots/:botId/executions

Returns executions for a specific bot. Supports cursor-based pagination.

Query Parameters:

Parameter	Type	Description
limit	number	Maximum number of executions to return.
cursor	string	Pagination cursor from a previous response.

---

Trigger Execution

POST /api/v1/bots/:botId/executions

Starts a new execution for the bot. Requires Write or Admin permission. Returns the execution ID.

Request Body (action bots):

For action bots, include the parameters defined in the bot's manifest:

{
  "params": {
    "searchQuery": "laptop",
    "maxResults": 10
  }
}

The system validates parameter names against the bot's manifest. If a parameter name does not match any defined parameter, the response includes a suggestion based on Levenshtein distance matching (e.g., "Unknown parameter 'serchQuery'. Did you mean 'searchQuery'?").

Example:

curl -X POST \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{"params": {"searchQuery": "laptop"}}' \
  "https://<deployment>.convex.site/api/v1/bots/<botId>/executions"

---

Get Execution Details

GET /api/v1/executions/:executionId

Returns details for a specific execution.

Response Fields:

Field	Type	Description
status	string	Current status (e.g., pending, running, completed, failed).
duration	number	Execution duration in milliseconds.
startedAt	number	Start timestamp (Unix ms).
completedAt	number	Completion timestamp (Unix ms). Null if still running.

---

Get Step Outputs

GET /api/v1/executions/:executionId/steps

Returns all step outputs for the execution. Each step includes its index, status, and any data produced.

---

Get Specific Step Output

GET /api/v1/executions/:executionId/steps/:index

Returns the output of a specific step by its zero-based index.

---

Get Extracted Data

GET /api/v1/executions/:executionId/extract

Returns the extracted data from a successful execution. Returns a 404 if the execution did not produce extraction data or has not completed.

---

Get Failure Context

GET /api/v1/executions/:executionId/failure

Returns failure details for a failed execution.

Response Fields:

Field	Type	Description
error	string	Error message describing what went wrong.
screenshotUrl	string	URL of the browser screenshot taken at the moment of failure.

---

Get Execution Logs

GET /api/v1/executions/:executionId/logs

Returns the log output from the execution. Includes runner logs, script output, and system messages.