# Run

## List Runs

> Retrieves a paginated list of runs for the authenticated user

```json
{"openapi":"3.0.0","info":{"title":"toolregistry.ai API","version":"1.0"},"servers":[{"url":"https://api.toolregistry.ai"}],"security":[{}],"paths":{"/v1/runs":{"get":{"description":"Retrieves a paginated list of runs for the authenticated user","operationId":"RunController_listRuns","parameters":[{"name":"includeEvents","required":false,"in":"query","schema":{"default":false,"type":"boolean"}},{"name":"userId","required":false,"in":"query","description":"Filter runs by user ID","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","description":"Filter runs by a single status value","schema":{"enum":["QUEUED","RUNNING","AUTH_REQUIRED","PAUSED","CANCELED","NO_SUCCESS","PARTIAL_SUCCESS","SUCCESS","FAILED"],"type":"string"}},{"name":"customerIntegrationIds","required":false,"in":"query","description":"Filter runs by customer integration IDs. Use repeated query params, for example: ?customerIntegrationIds=salesforce_abcd1234&customerIntegrationIds=hubspot_efgh5678","schema":{"type":"array","items":{"type":"string"}}},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"maximum":1000,"default":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":10,"type":"number"}}],"responses":{"200":{"description":"Runs retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunsWithPaginationDto"}}}},"401":{"description":"Unauthorized - invalid API key"},"500":{"description":"Internal server error"}},"summary":"List Runs","tags":["Run"]}}},"components":{"schemas":{"RunsWithPaginationDto":{"type":"object","properties":{"runs":{"description":"Runs matching the query","type":"array","items":{"$ref":"#/components/schemas/RunDto"}},"pagination":{"description":"Pagination metadata for the result set","allOf":[{"$ref":"#/components/schemas/PaginationDto"}]}},"required":["runs","pagination"]},"RunDto":{"type":"object","properties":{"runId":{"type":"string","description":"Unique identifier for the run","format":"uuid"},"repeatKey":{"type":"string","description":"Key passed or generated during creation to repeat the run later","format":"string"},"repeatRunId":{"type":"string","description":"The UUID of the run that was repeated","format":"uuid"},"userId":{"type":"string","description":"The ID of the user who initiated the run"},"status":{"type":"string","description":"Current status of the run","enum":["QUEUED","RUNNING","AUTH_REQUIRED","PAUSED","CANCELED","NO_SUCCESS","PARTIAL_SUCCESS","SUCCESS","FAILED"]},"executionPlanId":{"type":"string","description":"The UUID of the execution plan that was used for the run","format":"uuid"},"events":{"type":"array","description":"Array of events in the run","items":{"type":"object"}},"result":{"type":"object","description":"Result of the run execution"},"approvalStrategy":{"type":"string","description":"Approval strategy for the run","enum":["NONE","ON_TOOL_CALL","ON_START"]},"outputSchema":{"type":"object","description":"JSON Schema draft 7 schema for the run output format","format":"json-schema"},"inputSchema":{"type":"object","description":"JSON Schema draft 7 schema for run input format","format":"json-schema"},"input":{"type":"object","description":"Input provided when the run was created"},"intent":{"type":"string","description":"The intent or goal for the run"},"context":{"type":"string","description":"Additional context that was provided during run creation"},"createdAt":{"type":"string","description":"Timestamp when the run was created","format":"date-time"},"updatedAt":{"type":"string","description":"Timestamp when the run was last updated","format":"date-time"}},"required":["runId","repeatKey","status","executionPlanId","events","intent","context","createdAt","updatedAt"]},"PaginationDto":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"pageSize":{"type":"number","description":"Number of runs requested per page"},"total":{"type":"number","description":"Total number of runs matching the query"}},"required":["page","pageSize","total"]}}}}
```

## Create a new Run

> Creates a new run with the specified intent and selected integrations

```json
{"openapi":"3.0.0","info":{"title":"toolregistry.ai API","version":"1.0"},"servers":[{"url":"https://api.toolregistry.ai"}],"security":[{}],"paths":{"/v1/runs":{"post":{"description":"Creates a new run with the specified intent and selected integrations","operationId":"RunController_createRun","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRunRequest"}}}},"responses":{"201":{"description":"Run successfully created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRunResponse"}}}},"400":{"description":"Invalid request body or parameters"},"401":{"description":"Unauthorized - invalid API key"}},"summary":"Create a new Run","tags":["Run"]}}},"components":{"schemas":{"CreateRunRequest":{"type":"object","properties":{"intent":{"type":"string","description":"The intent or goal for the run"},"selectedCustomerIntegrationIds":{"description":"Array of selected customer integration IDs to use for the run, or use [\"*\"] to include all active integrations","type":"array","items":{"type":"string"}},"context":{"type":"string","description":"Additional context for the run execution"},"userId":{"type":"string","description":"The ID of the user who is initiating the run"},"approvalStrategy":{"type":"string","description":"Approval strategy for the run","enum":["NONE","ON_TOOL_CALL","ON_START"]},"repeatKey":{"type":"string","description":"The key of the run to repeat","format":"string"},"outputSchema":{"type":"object","description":"JSON Schema draft 7 schema for the run output format","format":"json-schema"},"passThrough":{"description":"Pass through data for the run, e.g. credentials for the integrations used in the run","type":"array","items":{"$ref":"#/components/schemas/CustomerProvidedPassThrough"}}},"required":["intent","selectedCustomerIntegrationIds","context","userId"]},"CustomerProvidedPassThrough":{"type":"object","properties":{"customerIntegrationId":{"type":"string","description":"The ID of the customer integration this pass-through data applies to."},"headers":{"type":"object","description":"Custom headers to include in requests for this integration."},"query":{"type":"object","description":"Custom query parameters to include in requests for this integration."},"values":{"description":"Provider-specific auth credentials. Use one of: AWS temporary credentials, AWS assume-role, or Okta service app (private_key_jwt). Only one type may be supplied per integration.","oneOf":[{"$ref":"#/components/schemas/CustomerProvidedAwsCredentials"},{"$ref":"#/components/schemas/CustomerProvidedAwsAssumeRole"},{"$ref":"#/components/schemas/CustomerProvidedOktaCredentials"}]}},"required":["customerIntegrationId"]},"CustomerProvidedAwsCredentials":{"type":"object","properties":{"accessKeyId":{"type":"string","description":"The AWS access key ID for authenticating requests."},"secretAccessKey":{"type":"string","description":"The AWS secret access key paired with the access key ID."},"sessionToken":{"type":"string","description":"The temporary session token for AWS STS credentials."}},"required":["accessKeyId","secretAccessKey","sessionToken"]},"CustomerProvidedAwsAssumeRole":{"type":"object","properties":{"roleArn":{"type":"string","description":"The ARN of the IAM role to assume for cross-account access."},"externalId":{"type":"string","description":"An external ID used to prevent confused deputy attacks when assuming the role."}},"required":["roleArn","externalId"]},"CustomerProvidedOktaCredentials":{"type":"object","properties":{"clientId":{"type":"string","description":"The Okta application client ID."},"kid":{"type":"string","description":"The key ID (kid) of the private key used to sign client assertions."},"privateKey":{"type":"string","description":"The PEM-encoded RSA private key used to sign client assertions (private_key_jwt)."},"oauthTokenUrl":{"type":"string","description":"The Okta OAuth 2.0 token endpoint URL for your organisation."},"scope":{"type":"string","description":"Space-separated list of Okta API scopes to request."},"host":{"type":"string","description":"Base host URL of your Okta organisation. If omitted, derived from oauthTokenUrl."}},"required":["clientId","kid","privateKey","oauthTokenUrl","scope"]},"CreateRunResponse":{"type":"object","properties":{"runId":{"type":"string","description":"Unique identifier for the created run","format":"uuid"},"repeatKey":{"type":"string","description":"Key passed or generated during creation to repeat the run later","format":"string"},"status":{"type":"string","description":"Current status of the run","enum":["QUEUED","RUNNING","AUTH_REQUIRED","PAUSED","CANCELED","NO_SUCCESS","PARTIAL_SUCCESS","SUCCESS","FAILED"]},"events":{"type":"array","description":"Array of events in the run","items":{"type":"object"}},"executionPlanId":{"type":"string","description":"The UUID of the execution plan that was used for the run","format":"uuid"},"plan":{"description":"Execution plan for the run","allOf":[{"$ref":"#/components/schemas/ExecPlanResponseDto"}]},"repeatRunId":{"type":"string","description":"The UUID of the run that is going to be repeated.","format":"uuid"}},"required":["runId","repeatKey","status","events","executionPlanId","plan"]},"ExecPlanResponseDto":{"type":"object","properties":{"planType":{"type":"string","description":"Plan serialization type","enum":["json","text"]},"plan":{"description":"Execution plan details","oneOf":[{"$ref":"#/components/schemas/ExecPlanDto"},{"type":"string"}]}},"required":["planType","plan"]},"ExecPlanDto":{"type":"object","properties":{"title":{"type":"string","description":"Optional human-readable title for the execution plan"},"description":{"type":"string","description":"High-level description of the execution plan"},"steps":{"description":"Ordered list of steps to execute the plan","type":"array","items":{"$ref":"#/components/schemas/ExecPlanStepDto"}}},"required":["description","steps"]},"ExecPlanStepDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the step"},"description":{"type":"string","description":"Step description"},"dependsOnSteps":{"description":"List of step IDs that must be completed first","type":"array","items":{"type":"string"}}},"required":["id","description","dependsOnSteps"]}}}}
```

## Approve or deny a run or its individual steps

> Approve or deny a run or its individual steps

```json
{"openapi":"3.0.0","info":{"title":"toolregistry.ai API","version":"1.0"},"servers":[{"url":"https://api.toolregistry.ai"}],"security":[{}],"paths":{"/v1/runs/approval":{"get":{"description":"Approve or deny a run or its individual steps","operationId":"RunController_runApproval","parameters":[{"name":"token","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"201":{"description":"Approval handled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/"}}}},"400":{"description":"Invalid request body or parameters"},"401":{"description":"Unauthorized - invalid API key"}},"summary":"Approve or deny a run or its individual steps","tags":["Run"]}}},"components":{"schemas":{}}}
```

## Get Run details

> Retrieves detailed information about a specific run

```json
{"openapi":"3.0.0","info":{"title":"toolregistry.ai API","version":"1.0"},"servers":[{"url":"https://api.toolregistry.ai"}],"security":[{}],"paths":{"/v1/runs/{runId}":{"get":{"description":"Retrieves detailed information about a specific run","operationId":"RunController_getRun","parameters":[{"name":"runId","required":true,"in":"path","description":"Unique identifier of the run to retrieve","schema":{"format":"uuid","type":"string"}},{"name":"includeEvents","required":false,"in":"query","schema":{"type":"string"},"description":"Include run events in the response (e.g., \"true\" or \"false\")"}],"responses":{"200":{"description":"Run details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunDto"}}}},"401":{"description":"Unauthorized - invalid API key"},"404":{"description":"Run not found"}},"summary":"Get Run details","tags":["Run"]}}},"components":{"schemas":{"RunDto":{"type":"object","properties":{"runId":{"type":"string","description":"Unique identifier for the run","format":"uuid"},"repeatKey":{"type":"string","description":"Key passed or generated during creation to repeat the run later","format":"string"},"repeatRunId":{"type":"string","description":"The UUID of the run that was repeated","format":"uuid"},"userId":{"type":"string","description":"The ID of the user who initiated the run"},"status":{"type":"string","description":"Current status of the run","enum":["QUEUED","RUNNING","AUTH_REQUIRED","PAUSED","CANCELED","NO_SUCCESS","PARTIAL_SUCCESS","SUCCESS","FAILED"]},"executionPlanId":{"type":"string","description":"The UUID of the execution plan that was used for the run","format":"uuid"},"events":{"type":"array","description":"Array of events in the run","items":{"type":"object"}},"result":{"type":"object","description":"Result of the run execution"},"approvalStrategy":{"type":"string","description":"Approval strategy for the run","enum":["NONE","ON_TOOL_CALL","ON_START"]},"outputSchema":{"type":"object","description":"JSON Schema draft 7 schema for the run output format","format":"json-schema"},"inputSchema":{"type":"object","description":"JSON Schema draft 7 schema for run input format","format":"json-schema"},"input":{"type":"object","description":"Input provided when the run was created"},"intent":{"type":"string","description":"The intent or goal for the run"},"context":{"type":"string","description":"Additional context that was provided during run creation"},"createdAt":{"type":"string","description":"Timestamp when the run was created","format":"date-time"},"updatedAt":{"type":"string","description":"Timestamp when the run was last updated","format":"date-time"}},"required":["runId","repeatKey","status","executionPlanId","events","intent","context","createdAt","updatedAt"]}}}}
```

## Abort a Run

> Aborts a running or queued run by its ID

```json
{"openapi":"3.0.0","info":{"title":"toolregistry.ai API","version":"1.0"},"servers":[{"url":"https://api.toolregistry.ai"}],"security":[{}],"paths":{"/v1/runs/{runId}":{"delete":{"description":"Aborts a running or queued run by its ID","operationId":"RunController_abortRun","parameters":[{"name":"runId","required":true,"in":"path","description":"Unique identifier of the run to abort","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"Run successfully aborted"},"401":{"description":"Unauthorized - invalid API key"},"404":{"description":"Run not found"}},"summary":"Abort a Run","tags":["Run"]}}}}
```

## Server-Sent Events stream for a Run

> Establishes a Server-Sent Events connection to stream real-time updates for a run

```json
{"openapi":"3.0.0","info":{"title":"toolregistry.ai API","version":"1.0"},"servers":[{"url":"https://api.toolregistry.ai"}],"security":[{}],"paths":{"/v1/runs/{runId}/sse":{"get":{"description":"Establishes a Server-Sent Events connection to stream real-time updates for a run","operationId":"RunController_sse","parameters":[{"name":"runId","required":true,"in":"path","description":"Unique identifier of the run to stream events for","schema":{"format":"uuid","type":"string"}},{"name":"includeToolCalls","required":false,"in":"query","schema":{"type":"string"},"description":"Include tool call details in the stream (e.g., \"true\" or \"false\"). By default, tool calls are not included and for step events, only text (description of the step) is included."}],"responses":{"200":{"description":"SSE stream established successfully","content":{"text/event-stream":{"schema":{"type":"string","description":"Server-sent events stream with run updates"}}}},"401":{"description":"Unauthorized - invalid API key"},"404":{"description":"Run not found"},"500":{"description":"Internal server error or stream error"}},"summary":"Server-Sent Events stream for a Run","tags":["Run"]}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.toolregistry.ai/api-documentation/run.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.