# 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":{"type":"array","items":{"$ref":"#/components/schemas/RunDto"}}}}},"401":{"description":"Unauthorized - invalid API key"},"500":{"description":"Internal server error"}},"summary":"List Runs","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"},"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"},"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"]}}}}
```

## 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/ExecPlanByIdResponseDto"}]},"repeatRunId":{"type":"string","description":"The UUID of the run that is going to be repeated.","format":"uuid"}},"required":["runId","repeatKey","status","events","executionPlanId","plan"]},"ExecPlanByIdResponseDto":{"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"},"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"},"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"]}}}}
```