{
"error": {
"code": "REQUEST_INVALID",
"message": "The request payload failed validation.",
"hint": "Correct the fields named in details and retry.",
"retryable": false,
"requestId": "req_01hxyz",
"details": [
{
"field": "query",
"issue": "query should not be empty"
}
]
}
}
{
"error": {
"code": "REQUEST_INVALID",
"message": "The request payload failed validation.",
"hint": "Correct the fields named in details and retry.",
"retryable": false,
"requestId": "req_01hxyz",
"details": [
{
"field": "query",
"issue": "query should not be empty"
}
]
}
}
{
"error": {
"code": "REQUEST_INVALID",
"message": "The request payload failed validation.",
"hint": "Correct the fields named in details and retry.",
"retryable": false,
"requestId": "req_01hxyz",
"details": [
{
"field": "query",
"issue": "query should not be empty"
}
]
}
}
{
"error": {
"code": "REQUEST_INVALID",
"message": "The request payload failed validation.",
"hint": "Correct the fields named in details and retry.",
"retryable": false,
"requestId": "req_01hxyz",
"details": [
{
"field": "query",
"issue": "query should not be empty"
}
]
}
}
{
"error": {
"code": "REQUEST_INVALID",
"message": "The request payload failed validation.",
"hint": "Correct the fields named in details and retry.",
"retryable": false,
"requestId": "req_01hxyz",
"details": [
{
"field": "query",
"issue": "query should not be empty"
}
]
}
}
{
"error": {
"code": "REQUEST_INVALID",
"message": "The request payload failed validation.",
"hint": "Correct the fields named in details and retry.",
"retryable": false,
"requestId": "req_01hxyz",
"details": [
{
"field": "query",
"issue": "query should not be empty"
}
]
}
}
{
"error": {
"code": "REQUEST_INVALID",
"message": "The request payload failed validation.",
"hint": "Correct the fields named in details and retry.",
"retryable": false,
"requestId": "req_01hxyz",
"details": [
{
"field": "query",
"issue": "query should not be empty"
}
]
}
}
{
"error": {
"code": "REQUEST_INVALID",
"message": "The request payload failed validation.",
"hint": "Correct the fields named in details and retry.",
"retryable": false,
"requestId": "req_01hxyz",
"details": [
{
"field": "query",
"issue": "query should not be empty"
}
]
}
}
This endpoint can be used to call any Tool on behalf of your user.You can find specific input parameters for a Tool you want to call in the Tools Reference, for example:
outputMode controls whether the provider body is returned on the execution or stored. When a Tool returns a large result (e.g. hundreds of CRM records), you can store the output server-side and receive a compact envelope instead of the full payload.
Mode
Behavior
inline
Returns the complete provider body on output.inline
auto
Returns output.inline when the body is at most 4000 tokens. A body larger than 4000 tokens is stored.
reference
Stores every body and returns output.resultId with output.stored.
A stored response has output.resultId and output.stored. output.inline is omitted.
output.stored is the envelope written with the stored body.
output.resultId (also available as stored.resultId) is an ID beginning with res_ that can be used to retrieve a stored result with Get Result or page through a records result with Get Result Rows.
Field
Meaning
byteSize
Byte size of the stored value.
tokenEstimate
Token count of the stored value. Same number as tokenBudget.fullOutputTokens.
shape
records or text. A string body is text. An object array is records, including one nested under records, data, results, or items. Any other value is stored as JSON text.
schema
Inferred schema for a records result. null for text, and null when the schema itself is larger than 4096 bytes.
sample
Up to 3 records. Each object keeps at most 12 keys, and strings are truncated to 240 characters. Omitted for text, and omitted when the schema plus sample exceed 4096 bytes.
recordCount
Number of records when shape is records. null for text.
recordsPointer
JSON Pointer to the record array when shape is records. null for text.
expiresAt
ISO timestamp, 86400 seconds after the result was stored.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Paragon Documentation","colors":{"primary":"#6645e6","light":"#6747e7","dark":"#6645e6"},"logo":{"light":"https://mintcdn.com/paragon/VsFfcYgo5-Qm6khT/logo/light.svg?fit=max\u0026auto=format\u0026n=VsFfcYgo5-Qm6khT\u0026q=85\u0026s=348909bc26f6451e89f4010d965f6e3f","dark":"https://mintcdn.com/paragon/VsFfcYgo5-Qm6khT/logo/dark.svg?fit=max\u0026auto=format\u0026n=VsFfcYgo5-Qm6khT\u0026q=85\u0026s=94df13e90b5d4116e55d031d5583fa1b","href":"https://docs.useparagon.com/"},"favicon":"https://mintcdn.com/paragon/jHdUQ3U2jexiiVjS/favicon.png?fit=max\u0026auto=format\u0026n=jHdUQ3U2jexiiVjS\u0026q=85\u0026s=92cb5c619d517e9c751282890f36033e","api":{"playground":{"proxy":false}},"background":{"decoration":"gradient"},"navbar":{"links":[{"href":"https://dashboard.useparagon.com/signup","label":"Sign up"}],"primary":{"type":"button","label":"Book a demo","href":"https://www.useparagon.com/book-demo"}},"footer":{"links":[{"header":"Home","items":[{"label":"Home","href":"https://www.useparagon.com"},{"label":"Sign Up","href":"https://dashboard.useparagon.com/signup"},{"label":"Book Demo","href":"https://www.useparagon.com/book-demo"},{"label":"Pricing","href":"https://www.useparagon.com/pricing"},{"label":"Careers","href":"https://www.useparagon.com/careers"}]},{"header":"Resources","items":[{"label":"Blog","href":"https://www.useparagon.com/blog"},{"label":"Case Studies","href":"https://www.useparagon.com/customers"},{"label":"ActionKit Playground","href":"https://try.actions.useparagon.com"},{"label":"Sync Playground","href":"https://try.sync.useparagon.com"},{"label":"Product Tour","href":"https://www.useparagon.com/product-tour-landing"}]},{"header":"Legal","items":[{"label":"Privacy Policy","href":"https://www.useparagon.com/privacy-policy"},{"label":"Terms of Service","href":"https://www.useparagon.com/terms-of-service"},{"label":"Your Privacy Choices","href":"/optout"}]}]},"fonts":{"heading":{"family":"Helvetica Now Display Medium","weight":400,"source":"https://framerusercontent.com/assets/OKeqk0lRqQ5xtPOYZPiID295g.woff2","format":"woff2"}},"integrations":{"ga4":{"measurementId":"G-DH6VCLG1X6"},"gtm":{"tagId":"GTM-WCJFR4H"},"cookies":{"key":"paragon_docs_integrations_consent","value":"granted"}},"errors":{"404":{"redirect":false}},"styling":{"latex":true},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"paragon","hasAudioNarration":false,"actualSubdomain":"paragon","customDomains":["docs.useparagon.com"],"gitSource":{"type":"github","owner":"useparagon-internal","repo":"docs-mintlify","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"chroma":{"liveDeploymentHistoryId":"6ae3c95c97b1ae3164b1afaa","collectionId":"0d0c583a-8145-4f79-88fb-810e552b4378","schemaVersion":"v3","latestBuiltDeploymentHistoryId":"6ae3c95c97b1ae3164b1afaa"},"feedback":{"edits":false,"thumbs":true},"entitlements":{"AI_CHAT":{"status":"ENABLED"},"REMOVE_BRANDING":{"status":"ENABLED"},"CONTEXTUAL_FEEDBACK":{"status":"ENABLED"},"CODE_SNIPPET_FEEDBACK":{"status":"ENABLED"},"WEB_MCP":{"status":"ENABLED"},"NARRATION":{"status":"ENABLED"}},"buildId":"6ae3c95c97b1ae3164b1afaa","clientVersion":"0.0.4021","searchFilterCounts":[{"language":"default","tag":"ActionKit","count":1114},{"language":"default","tag":"Integrations Reference","count":1103},{"language":"default","tag":"Tools","count":863},{"language":"default","tag":"Triggers","count":147},{"language":"default","tag":"Integrations","count":126},{"language":"default","tag":"Integration Providers","count":126},{"language":"default","tag":"Managed Sync","count":67},{"language":"default","tag":"Platform","count":56},{"language":"default","tag":"Workflows","count":54},{"language":"default","tag":"Salesforce","count":51}]},"assistantConfig":{},"basePath":"","hasChatPermissions":true,"hasWebMcpPermissions":true,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"byok-sep-25","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"vite-origin","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-updated-9-15","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[{"filePath":"style.css","content":"#top-aligned-table td{vertical-align:top;padding:8px}#footer a[href='/optout']{overflow:auto;max-width:100%}footer>div{padding-top:4rem!important}a.nav-tabs-item[href=\"/resources/integrations\"]{margin-left:auto}div.nav-tabs{width:100%}"}],"page":{"pagePath":"agent-os/tools/create-execution","slug":"/agent-os/tools/create-execution","pageMetadata":{"title":"Run Tool","openapi":"agent-os/openapi/tools.json POST /api/tools/projects/{projectId}/executions","description":"Run a tool on behalf of a Connected User.","href":"/agent-os/tools/create-execution","hidden":true},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Run a tool on behalf of a Connected User.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,li:`li`,p:`p`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,..._provideComponents(),...props.components},{Heading,Table}=_components;if(!Heading)_missingMdxReference(`Heading`,true);if(!Table)_missingMdxReference(`Table`,true);return _jsxs(_Fragment,{children:[_jsx(_components.p,{children:`This endpoint can be used to call any Tool on behalf of your user.`}),`\n`,_jsx(_components.p,{children:`You can find specific input parameters for a Tool you want to call in the Tools Reference, for example:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:_jsx(_components.a,{href:`/actionkit/integrations/slack/SLACK_SEND_MESSAGE`,children:`Slack: Send Message`})}),`\n`,_jsx(_components.li,{children:_jsx(_components.a,{href:`/actionkit/integrations/googledrive/GOOGLE_DRIVE_DOWNLOAD_FILE`,children:`Google: Drive Download File`})}),`\n`,_jsx(_components.li,{children:_jsx(_components.a,{href:`/actionkit/integrations/gmail/GMAIL_SEARCH_FOR_EMAIL`,children:`Gmail: Search Emails`})}),`\n`]}),`\n`,_jsx(_components.p,{children:`Each Tool in the Reference is an example call to this endpoint.`}),`\n`,_jsx(Heading,{level:`3`,id:`output-modes`,children:`Output Modes`}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`outputMode`}),` controls whether the provider body is returned on the execution or stored. When a Tool returns a large result (e.g. hundreds of CRM records), you can store the output server-side and receive a compact envelope instead of the full payload.`]}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Mode`}),_jsx(_components.th,{children:`Behavior`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`inline`})}),_jsxs(_components.td,{children:[`Returns the complete provider body on `,_jsx(_components.code,{children:`output.inline`})]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`auto`})}),_jsxs(_components.td,{children:[`Returns `,_jsx(_components.code,{children:`output.inline`}),` when the body is at most 4000 tokens. A body larger than 4000 tokens is stored.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`reference`})}),_jsxs(_components.td,{children:[`Stores every body and returns `,_jsx(_components.code,{children:`output.resultId`}),` with `,_jsx(_components.code,{children:`output.stored`}),`.`]})]})]})]}),`\n`,_jsxs(_components.p,{children:[`A stored response has `,_jsx(_components.code,{children:`output.resultId`}),` and `,_jsx(_components.code,{children:`output.stored`}),`. `,_jsx(_components.code,{children:`output.inline`}),` is omitted.`]}),`\n`,_jsx(Heading,{level:`2`,id:`stored-result-envelope`,children:`Stored Result Envelope`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`output.stored`}),` is the envelope written with the stored body.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`output.resultId`}),` (also available as `,_jsx(_components.code,{children:`stored.resultId`}),`) is an ID beginning with `,_jsx(_components.code,{children:`res_`}),` that can be used to retrieve a stored result with `,_jsx(_components.a,{href:`/agent-os/tools/get-result`,children:`Get Result`}),` or page through a `,_jsx(_components.code,{children:`records`}),` result with `,_jsx(_components.a,{href:`/agent-os/tools/get-result-rows`,children:`Get Result Rows`}),`.`]}),`\n`]}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Field`}),_jsx(_components.th,{children:`Meaning`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`byteSize`})}),_jsx(_components.td,{children:`Byte size of the stored value.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`tokenEstimate`})}),_jsxs(_components.td,{children:[`Token count of the stored value. Same number as `,_jsx(_components.code,{children:`tokenBudget.fullOutputTokens`}),`.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`shape`})}),_jsxs(_components.td,{children:[_jsx(_components.code,{children:`records`}),` or `,_jsx(_components.code,{children:`text`}),`. A string body is `,_jsx(_components.code,{children:`text`}),`. An object array is `,_jsx(_components.code,{children:`records`}),`, including one nested under `,_jsx(_components.code,{children:`records`}),`, `,_jsx(_components.code,{children:`data`}),`, `,_jsx(_components.code,{children:`results`}),`, or `,_jsx(_components.code,{children:`items`}),`. Any other value is stored as JSON text.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`schema`})}),_jsxs(_components.td,{children:[`Inferred schema for a records result. `,_jsx(_components.code,{children:`null`}),` for text, and `,_jsx(_components.code,{children:`null`}),` when the schema itself is larger than 4096 bytes.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`sample`})}),_jsx(_components.td,{children:`Up to 3 records. Each object keeps at most 12 keys, and strings are truncated to 240 characters. Omitted for text, and omitted when the schema plus sample exceed 4096 bytes.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`recordCount`})}),_jsxs(_components.td,{children:[`Number of records when `,_jsx(_components.code,{children:`shape`}),` is `,_jsx(_components.code,{children:`records`}),`. `,_jsx(_components.code,{children:`null`}),` for `,_jsx(_components.code,{children:`text`}),`.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`recordsPointer`})}),_jsxs(_components.td,{children:[`JSON Pointer to the record array when `,_jsx(_components.code,{children:`shape`}),` is `,_jsx(_components.code,{children:`records`}),`. `,_jsx(_components.code,{children:`null`}),` for `,_jsx(_components.code,{children:`text`}),`.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`expiresAt`})}),_jsx(_components.td,{children:`ISO timestamp, 86400 seconds after the result was stored.`})]})]})]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Run Tool","openapi":"agent-os/openapi/tools.json POST /api/tools/projects/{projectId}/executions","description":"Run a tool on behalf of a Connected User.","href":"/agent-os/tools/create-execution","hidden":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Output Modes","slug":"output-modes","depth":3,"children":[]},{"title":"Stored Result Envelope","slug":"stored-result-envelope","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":["/_mintlify/custom/paragon/b66e6962cf6c82d8/cookiebot-mintlify-consent.js"],"openApiReferenceData":{"operation":{"operationId":"createExecution","summary":"Run Tool","parameters":["b5184742-a4f8-4aa3-ae01-d444b2cbb091","f7e61c21-f888-4557-b4ab-204a761b229c","7e892d9a-ba97-4ef7-a4c8-f09a385a805e","840323d5-21a9-4d93-8326-f382ee289f96"],"requestBody":"772a0bd3-b2aa-4742-beb2-7980fcbdb721","responses":{"200":"9568e7a7-e01f-4ddc-b621-50a57159a927","202":"ddf7d46b-4648-47f6-9daf-26dcf9b133f0","400":"1876714b-03af-4b89-a775-dd4a2c3ac42e","401":"4685f9eb-719e-4b5a-b71c-4091407668aa","403":"de213661-167a-492e-8f3b-dfabc3fc2116","404":"bb4e7891-1f5b-48e2-9254-b1e1a15ac94b"},"method":"post","type":"path","servers":["96b49547-43b5-4af8-a103-9e26d7f639f9","98868f35-79ab-45e4-80d5-0e593a169ed2"],"security":["dcde3fc0-d77c-4eee-bf0e-57f01c2affd7"],"path":"/api/tools/projects/{projectId}/executions","baseUrlOptions":["https://agentos.useparagon.com","https://agentos.eu.paragon.so"],"title":"Run Tool","description":"Run a tool on behalf of a Connected User.","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated","disableProxy":true},"dependencies":{"parameters":{"b5184742-a4f8-4aa3-ae01-d444b2cbb091":{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid","isRequired":true,"uniqueKey":"","typeLabel":"string\u003cuuid>"}},"f7e61c21-f888-4557-b4ab-204a761b229c":{"name":"Prefer","in":"header","schema":{"type":"string","example":"wait=25","description":"RFC 7240 wait. Default 25 seconds. wait=0 returns 202 immediately.","uniqueKey":"","typeLabel":"string"},"description":"RFC 7240 wait. Default 25 seconds. wait=0 returns 202 immediately."},"7e892d9a-ba97-4ef7-a4c8-f09a385a805e":{"name":"Idempotency-Key","in":"header","schema":{"type":"string","description":"Stored on the row. Not used to replay an earlier execution.","uniqueKey":"","typeLabel":"string"},"description":"Stored on the row. Not used to replay an earlier execution."},"840323d5-21a9-4d93-8326-f382ee289f96":{"name":"x-paragon-credential","in":"header","schema":{"type":"string","description":"Forwarded as the execution credential. Omit to send none.","uniqueKey":"","typeLabel":"string"},"description":"Forwarded as the execution credential. Omit to send none."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["intentName"],"additionalProperties":false,"properties":{"intentName":{"type":"string","minLength":1,"maxLength":512,"isRequired":true,"uniqueKey":"intentName","typeLabel":"string"},"args":{"type":"object","additionalProperties":true,"uniqueKey":"args","typeLabel":"object"},"timeoutMs":{"type":"integer","minimum":1000,"maximum":120000,"default":60000,"uniqueKey":"timeoutMs","typeLabel":"integer"},"outputMode":{"type":"string","enum":["inline","auto","reference"],"default":"auto","uniqueKey":"outputMode","typeLabel":"enum\u003cstring>"}},"uniqueKey":"","typeLabel":"object"},"example":{"intentName":"EXAMPLE_LIST_RECORDS","args":{"limit":10},"outputMode":"auto"},"examples":{"Example":{"title":"Example","value":{"intentName":"EXAMPLE_LIST_RECORDS","args":{"limit":10},"outputMode":"auto"}}},"exampleType":"examples"}},"exampleType":"examples"},"responses":{"9568e7a7-e01f-4ddc-b621-50a57159a927":{"description":"The call settled within the Prefer wait.","content":{"application/json":{"schema":{"type":"object","required":["executionId","engine","status","startedAt","settledAt","durationMs","calls"],"properties":{"executionId":{"type":"string","isRequired":true,"uniqueKey":"executionId","typeLabel":"string"},"engine":{"type":"string","enum":["declarative"],"isRequired":true,"uniqueKey":"engine","typeLabel":"enum\u003cstring>"},"status":{"type":"string","enum":["running","completed","failed","timeout","cancelled"],"isRequired":true,"uniqueKey":"status","typeLabel":"enum\u003cstring>"},"startedAt":{"type":"string","format":"date-time","isRequired":true,"uniqueKey":"startedAt","typeLabel":"string\u003cdate-time>"},"settledAt":{"oneOf":[{"type":"string","format":"date-time","isRequired":true,"uniqueKey":"settledAt.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","isRequired":true,"uniqueKey":"settledAt.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"settledAt","typeLabel":"string\u003cdate-time> | null"},"durationMs":{"oneOf":[{"type":"number","isRequired":true,"uniqueKey":"durationMs.oneOf.0","typeLabel":"number"},{"type":"null","isRequired":true,"uniqueKey":"durationMs.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"durationMs","typeLabel":"number | null"},"calls":{"type":"array","items":{"type":"object","required":["seq","kind","tool","integration","decision","upstreamStatus"],"properties":{"seq":{"type":"integer","isRequired":true,"uniqueKey":"calls.items.[INDEX].seq","typeLabel":"integer"},"kind":{"type":"string","enum":["run"],"isRequired":true,"uniqueKey":"calls.items.[INDEX].kind","typeLabel":"enum\u003cstring>"},"tool":{"type":"string","isRequired":true,"uniqueKey":"calls.items.[INDEX].tool","typeLabel":"string"},"integration":{"type":"string","isRequired":true,"uniqueKey":"calls.items.[INDEX].integration","typeLabel":"string"},"decision":{"type":"string","enum":["allowed","denied_scope","denied_rate","expired"],"isRequired":true,"uniqueKey":"calls.items.[INDEX].decision","typeLabel":"enum\u003cstring>"},"upstreamStatus":{"oneOf":[{"type":"integer","isRequired":true,"uniqueKey":"calls.items.[INDEX].upstreamStatus.oneOf.0","typeLabel":"integer"},{"type":"null","isRequired":true,"uniqueKey":"calls.items.[INDEX].upstreamStatus.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"calls.items.[INDEX].upstreamStatus","typeLabel":"integer | null"}},"uniqueKey":"calls.items.[INDEX]","typeLabel":"object"},"isRequired":true,"uniqueKey":"calls","typeLabel":"object[]"},"deadlineMs":{"type":"number","uniqueKey":"deadlineMs","typeLabel":"number"},"killed":{"type":"boolean","uniqueKey":"killed","typeLabel":"boolean"},"cancelledBy":{"type":"string","enum":["operator"],"uniqueKey":"cancelledBy","typeLabel":"enum\u003cstring>"},"output":{"type":"object","properties":{"inline":{"oneOf":[{}],"uniqueKey":"output.inline","typeLabel":"any"},"resultId":{"type":"string","uniqueKey":"output.resultId","typeLabel":"string"},"stored":{"type":"object","required":["resultId","executionId","tool","integration","byteSize","tokenEstimate","shape","expiresAt","tokenBudget"],"properties":{"resultId":{"type":"string","isRequired":true,"uniqueKey":"output.stored.resultId","typeLabel":"string"},"executionId":{"type":"string","isRequired":true,"uniqueKey":"output.stored.executionId","typeLabel":"string"},"tool":{"type":"string","isRequired":true,"uniqueKey":"output.stored.tool","typeLabel":"string"},"integration":{"type":"string","isRequired":true,"uniqueKey":"output.stored.integration","typeLabel":"string"},"byteSize":{"type":"integer","isRequired":true,"uniqueKey":"output.stored.byteSize","typeLabel":"integer"},"tokenEstimate":{"type":"integer","isRequired":true,"uniqueKey":"output.stored.tokenEstimate","typeLabel":"integer"},"shape":{"type":"string","enum":["records","text"],"isRequired":true,"uniqueKey":"output.stored.shape","typeLabel":"enum\u003cstring>"},"expiresAt":{"type":"string","format":"date-time","isRequired":true,"uniqueKey":"output.stored.expiresAt","typeLabel":"string\u003cdate-time>"},"tokenBudget":{"type":"object","required":["fullOutputTokens","returnedTokens","savedTokens"],"properties":{"fullOutputTokens":{"type":"integer","isRequired":true,"uniqueKey":"output.stored.tokenBudget.fullOutputTokens","typeLabel":"integer"},"returnedTokens":{"type":"integer","isRequired":true,"uniqueKey":"output.stored.tokenBudget.returnedTokens","typeLabel":"integer"},"savedTokens":{"type":"integer","isRequired":true,"uniqueKey":"output.stored.tokenBudget.savedTokens","typeLabel":"integer"}},"isRequired":true,"uniqueKey":"output.stored.tokenBudget","typeLabel":"object"},"recordCount":{"oneOf":[{"type":"integer","uniqueKey":"output.stored.recordCount.oneOf.0","typeLabel":"integer"},{"type":"null","uniqueKey":"output.stored.recordCount.oneOf.1","typeLabel":"null"}],"uniqueKey":"output.stored.recordCount","typeLabel":"integer | null"},"recordsPointer":{"oneOf":[{"type":"string","uniqueKey":"output.stored.recordsPointer.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"output.stored.recordsPointer.oneOf.1","typeLabel":"null"}],"uniqueKey":"output.stored.recordsPointer","typeLabel":"string | null"},"totalChars":{"oneOf":[{"type":"integer","uniqueKey":"output.stored.totalChars.oneOf.0","typeLabel":"integer"},{"type":"null","uniqueKey":"output.stored.totalChars.oneOf.1","typeLabel":"null"}],"uniqueKey":"output.stored.totalChars","typeLabel":"integer | null"},"schema":{"oneOf":[{}],"uniqueKey":"output.stored.schema","typeLabel":"any"},"sample":{"oneOf":[{}],"uniqueKey":"output.stored.sample","typeLabel":"any"}},"uniqueKey":"output.stored","typeLabel":"object"}},"uniqueKey":"output","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"example":{"executionId":"exec_0123456789abcdef0123456789abcdef","engine":"declarative","status":"completed","startedAt":"2026-10-05T21:00:00.000Z","settledAt":"2026-10-05T21:00:01.200Z","durationMs":1200,"calls":[{"seq":1,"kind":"run","tool":"EXAMPLE_LIST_RECORDS","integration":"example","decision":"allowed","upstreamStatus":200}],"output":{"inline":{"records":[]}}},"examples":{"Example":{"title":"Example","value":{"executionId":"exec_0123456789abcdef0123456789abcdef","engine":"declarative","status":"completed","startedAt":"2026-10-05T21:00:00.000Z","settledAt":"2026-10-05T21:00:01.200Z","durationMs":1200,"calls":[{"seq":1,"kind":"run","tool":"EXAMPLE_LIST_RECORDS","integration":"example","decision":"allowed","upstreamStatus":200}],"output":{"inline":{"records":[]}}}}},"exampleType":"examples"}},"exampleType":"examples"},"ddf7d46b-4648-47f6-9daf-26dcf9b133f0":{"description":"Still running. Location is the execution URL. Retry-After is 1.","headers":{"Location":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string","example":"1"}}},"content":{"application/json":{"schema":{"type":"object","required":["executionId","engine","status","startedAt","settledAt","durationMs","calls"],"properties":{"executionId":{"type":"string","isRequired":true,"uniqueKey":"executionId","typeLabel":"string"},"engine":{"type":"string","enum":["declarative"],"isRequired":true,"uniqueKey":"engine","typeLabel":"enum\u003cstring>"},"status":{"type":"string","enum":["running","completed","failed","timeout","cancelled"],"isRequired":true,"uniqueKey":"status","typeLabel":"enum\u003cstring>"},"startedAt":{"type":"string","format":"date-time","isRequired":true,"uniqueKey":"startedAt","typeLabel":"string\u003cdate-time>"},"settledAt":{"oneOf":[{"type":"string","format":"date-time","isRequired":true,"uniqueKey":"settledAt.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","isRequired":true,"uniqueKey":"settledAt.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"settledAt","typeLabel":"string\u003cdate-time> | null"},"durationMs":{"oneOf":[{"type":"number","isRequired":true,"uniqueKey":"durationMs.oneOf.0","typeLabel":"number"},{"type":"null","isRequired":true,"uniqueKey":"durationMs.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"durationMs","typeLabel":"number | null"},"calls":{"type":"array","items":{"type":"object","required":["seq","kind","tool","integration","decision","upstreamStatus"],"properties":{"seq":{"type":"integer","isRequired":true,"uniqueKey":"calls.items.[INDEX].seq","typeLabel":"integer"},"kind":{"type":"string","enum":["run"],"isRequired":true,"uniqueKey":"calls.items.[INDEX].kind","typeLabel":"enum\u003cstring>"},"tool":{"type":"string","isRequired":true,"uniqueKey":"calls.items.[INDEX].tool","typeLabel":"string"},"integration":{"type":"string","isRequired":true,"uniqueKey":"calls.items.[INDEX].integration","typeLabel":"string"},"decision":{"type":"string","enum":["allowed","denied_scope","denied_rate","expired"],"isRequired":true,"uniqueKey":"calls.items.[INDEX].decision","typeLabel":"enum\u003cstring>"},"upstreamStatus":{"oneOf":[{"type":"integer","isRequired":true,"uniqueKey":"calls.items.[INDEX].upstreamStatus.oneOf.0","typeLabel":"integer"},{"type":"null","isRequired":true,"uniqueKey":"calls.items.[INDEX].upstreamStatus.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"calls.items.[INDEX].upstreamStatus","typeLabel":"integer | null"}},"uniqueKey":"calls.items.[INDEX]","typeLabel":"object"},"isRequired":true,"uniqueKey":"calls","typeLabel":"object[]"},"deadlineMs":{"type":"number","uniqueKey":"deadlineMs","typeLabel":"number"},"killed":{"type":"boolean","uniqueKey":"killed","typeLabel":"boolean"},"cancelledBy":{"type":"string","enum":["operator"],"uniqueKey":"cancelledBy","typeLabel":"enum\u003cstring>"},"output":{"type":"object","properties":{"inline":{"oneOf":[{}],"uniqueKey":"output.inline","typeLabel":"any"},"resultId":{"type":"string","uniqueKey":"output.resultId","typeLabel":"string"},"stored":{"type":"object","required":["resultId","executionId","tool","integration","byteSize","tokenEstimate","shape","expiresAt","tokenBudget"],"properties":{"resultId":{"type":"string","isRequired":true,"uniqueKey":"output.stored.resultId","typeLabel":"string"},"executionId":{"type":"string","isRequired":true,"uniqueKey":"output.stored.executionId","typeLabel":"string"},"tool":{"type":"string","isRequired":true,"uniqueKey":"output.stored.tool","typeLabel":"string"},"integration":{"type":"string","isRequired":true,"uniqueKey":"output.stored.integration","typeLabel":"string"},"byteSize":{"type":"integer","isRequired":true,"uniqueKey":"output.stored.byteSize","typeLabel":"integer"},"tokenEstimate":{"type":"integer","isRequired":true,"uniqueKey":"output.stored.tokenEstimate","typeLabel":"integer"},"shape":{"type":"string","enum":["records","text"],"isRequired":true,"uniqueKey":"output.stored.shape","typeLabel":"enum\u003cstring>"},"expiresAt":{"type":"string","format":"date-time","isRequired":true,"uniqueKey":"output.stored.expiresAt","typeLabel":"string\u003cdate-time>"},"tokenBudget":{"type":"object","required":["fullOutputTokens","returnedTokens","savedTokens"],"properties":{"fullOutputTokens":{"type":"integer","isRequired":true,"uniqueKey":"output.stored.tokenBudget.fullOutputTokens","typeLabel":"integer"},"returnedTokens":{"type":"integer","isRequired":true,"uniqueKey":"output.stored.tokenBudget.returnedTokens","typeLabel":"integer"},"savedTokens":{"type":"integer","isRequired":true,"uniqueKey":"output.stored.tokenBudget.savedTokens","typeLabel":"integer"}},"isRequired":true,"uniqueKey":"output.stored.tokenBudget","typeLabel":"object"},"recordCount":{"oneOf":[{"type":"integer","uniqueKey":"output.stored.recordCount.oneOf.0","typeLabel":"integer"},{"type":"null","uniqueKey":"output.stored.recordCount.oneOf.1","typeLabel":"null"}],"uniqueKey":"output.stored.recordCount","typeLabel":"integer | null"},"recordsPointer":{"oneOf":[{"type":"string","uniqueKey":"output.stored.recordsPointer.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"output.stored.recordsPointer.oneOf.1","typeLabel":"null"}],"uniqueKey":"output.stored.recordsPointer","typeLabel":"string | null"},"totalChars":{"oneOf":[{"type":"integer","uniqueKey":"output.stored.totalChars.oneOf.0","typeLabel":"integer"},{"type":"null","uniqueKey":"output.stored.totalChars.oneOf.1","typeLabel":"null"}],"uniqueKey":"output.stored.totalChars","typeLabel":"integer | null"},"schema":{"oneOf":[{}],"uniqueKey":"output.stored.schema","typeLabel":"any"},"sample":{"oneOf":[{}],"uniqueKey":"output.stored.sample","typeLabel":"any"}},"uniqueKey":"output.stored","typeLabel":"object"}},"uniqueKey":"output","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"example":{"executionId":"exec_0123456789abcdef0123456789abcdef","engine":"declarative","status":"running","startedAt":"2026-10-05T21:00:00.000Z","settledAt":null,"durationMs":null,"calls":[]},"examples":{"Example":{"title":"Example","value":{"executionId":"exec_0123456789abcdef0123456789abcdef","engine":"declarative","status":"running","startedAt":"2026-10-05T21:00:00.000Z","settledAt":null,"durationMs":null,"calls":[]}}},"exampleType":"examples"}},"exampleType":"examples"},"1876714b-03af-4b89-a775-dd4a2c3ac42e":{"description":"Error envelope.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint","retryable","requestId"],"properties":{"code":{"type":"string","isRequired":true,"uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"hint":{"type":"string","isRequired":true,"uniqueKey":"error.hint","typeLabel":"string"},"retryable":{"type":"boolean","isRequired":true,"uniqueKey":"error.retryable","typeLabel":"boolean"},"requestId":{"type":"string","isRequired":true,"uniqueKey":"error.requestId","typeLabel":"string"},"retryAfterMs":{"type":"integer","uniqueKey":"error.retryAfterMs","typeLabel":"integer"},"details":{"type":"array","items":{"type":"object","required":["field","issue"],"properties":{"field":{"type":"string","isRequired":true,"uniqueKey":"error.details.items.[INDEX].field","typeLabel":"string"},"issue":{"type":"string","isRequired":true,"uniqueKey":"error.details.items.[INDEX].issue","typeLabel":"string"}},"uniqueKey":"error.details.items.[INDEX]","typeLabel":"object"},"uniqueKey":"error.details","typeLabel":"object[]"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"example":{"error":{"code":"REQUEST_INVALID","message":"The request payload failed validation.","hint":"Correct the fields named in details and retry.","retryable":false,"requestId":"req_01hxyz","details":[{"field":"query","issue":"query should not be empty"}]}},"examples":{"Example":{"title":"Example","value":{"error":{"code":"REQUEST_INVALID","message":"The request payload failed validation.","hint":"Correct the fields named in details and retry.","retryable":false,"requestId":"req_01hxyz","details":[{"field":"query","issue":"query should not be empty"}]}}}},"exampleType":"examples"}},"exampleType":"examples"},"4685f9eb-719e-4b5a-b71c-4091407668aa":{"description":"Error envelope.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint","retryable","requestId"],"properties":{"code":{"type":"string","isRequired":true,"uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"hint":{"type":"string","isRequired":true,"uniqueKey":"error.hint","typeLabel":"string"},"retryable":{"type":"boolean","isRequired":true,"uniqueKey":"error.retryable","typeLabel":"boolean"},"requestId":{"type":"string","isRequired":true,"uniqueKey":"error.requestId","typeLabel":"string"},"retryAfterMs":{"type":"integer","uniqueKey":"error.retryAfterMs","typeLabel":"integer"},"details":{"type":"array","items":{"type":"object","required":["field","issue"],"properties":{"field":{"type":"string","isRequired":true,"uniqueKey":"error.details.items.[INDEX].field","typeLabel":"string"},"issue":{"type":"string","isRequired":true,"uniqueKey":"error.details.items.[INDEX].issue","typeLabel":"string"}},"uniqueKey":"error.details.items.[INDEX]","typeLabel":"object"},"uniqueKey":"error.details","typeLabel":"object[]"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"example":{"error":{"code":"REQUEST_INVALID","message":"The request payload failed validation.","hint":"Correct the fields named in details and retry.","retryable":false,"requestId":"req_01hxyz","details":[{"field":"query","issue":"query should not be empty"}]}},"examples":{"Example":{"title":"Example","value":{"error":{"code":"REQUEST_INVALID","message":"The request payload failed validation.","hint":"Correct the fields named in details and retry.","retryable":false,"requestId":"req_01hxyz","details":[{"field":"query","issue":"query should not be empty"}]}}}},"exampleType":"examples"}},"exampleType":"examples"},"de213661-167a-492e-8f3b-dfabc3fc2116":{"description":"Error envelope.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint","retryable","requestId"],"properties":{"code":{"type":"string","isRequired":true,"uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"hint":{"type":"string","isRequired":true,"uniqueKey":"error.hint","typeLabel":"string"},"retryable":{"type":"boolean","isRequired":true,"uniqueKey":"error.retryable","typeLabel":"boolean"},"requestId":{"type":"string","isRequired":true,"uniqueKey":"error.requestId","typeLabel":"string"},"retryAfterMs":{"type":"integer","uniqueKey":"error.retryAfterMs","typeLabel":"integer"},"details":{"type":"array","items":{"type":"object","required":["field","issue"],"properties":{"field":{"type":"string","isRequired":true,"uniqueKey":"error.details.items.[INDEX].field","typeLabel":"string"},"issue":{"type":"string","isRequired":true,"uniqueKey":"error.details.items.[INDEX].issue","typeLabel":"string"}},"uniqueKey":"error.details.items.[INDEX]","typeLabel":"object"},"uniqueKey":"error.details","typeLabel":"object[]"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"example":{"error":{"code":"REQUEST_INVALID","message":"The request payload failed validation.","hint":"Correct the fields named in details and retry.","retryable":false,"requestId":"req_01hxyz","details":[{"field":"query","issue":"query should not be empty"}]}},"examples":{"Example":{"title":"Example","value":{"error":{"code":"REQUEST_INVALID","message":"The request payload failed validation.","hint":"Correct the fields named in details and retry.","retryable":false,"requestId":"req_01hxyz","details":[{"field":"query","issue":"query should not be empty"}]}}}},"exampleType":"examples"}},"exampleType":"examples"},"bb4e7891-1f5b-48e2-9254-b1e1a15ac94b":{"description":"Error envelope.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint","retryable","requestId"],"properties":{"code":{"type":"string","isRequired":true,"uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"hint":{"type":"string","isRequired":true,"uniqueKey":"error.hint","typeLabel":"string"},"retryable":{"type":"boolean","isRequired":true,"uniqueKey":"error.retryable","typeLabel":"boolean"},"requestId":{"type":"string","isRequired":true,"uniqueKey":"error.requestId","typeLabel":"string"},"retryAfterMs":{"type":"integer","uniqueKey":"error.retryAfterMs","typeLabel":"integer"},"details":{"type":"array","items":{"type":"object","required":["field","issue"],"properties":{"field":{"type":"string","isRequired":true,"uniqueKey":"error.details.items.[INDEX].field","typeLabel":"string"},"issue":{"type":"string","isRequired":true,"uniqueKey":"error.details.items.[INDEX].issue","typeLabel":"string"}},"uniqueKey":"error.details.items.[INDEX]","typeLabel":"object"},"uniqueKey":"error.details","typeLabel":"object[]"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"example":{"error":{"code":"REQUEST_INVALID","message":"The request payload failed validation.","hint":"Correct the fields named in details and retry.","retryable":false,"requestId":"req_01hxyz","details":[{"field":"query","issue":"query should not be empty"}]}},"examples":{"Example":{"title":"Example","value":{"error":{"code":"REQUEST_INVALID","message":"The request payload failed validation.","hint":"Correct the fields named in details and retry.","retryable":false,"requestId":"req_01hxyz","details":[{"field":"query","issue":"query should not be empty"}]}}}},"exampleType":"examples"}},"exampleType":"examples"}},"security":{"dcde3fc0-d77c-4eee-bf0e-57f01c2affd7":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Your [Paragon User Token](/getting-started/installing-the-connect-sdk#setup) (JWT), which you can generate using your project's signing keys.","scopes":[],"schemeName":"bearerAuth"}}},"servers":{"96b49547-43b5-4af8-a103-9e26d7f639f9":{"url":"https://agentos.useparagon.com","description":"Production US Cloud"},"98868f35-79ab-45e4-80d5-0e593a169ed2":{"url":"https://agentos.eu.paragon.so","description":"Production EU Cloud"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Your [Paragon User Token](/getting-started/installing-the-connect-sdk#setup) (JWT), which you can generate using your project's signing keys.","scopes":[],"schemeName":"bearerAuth"},"schema":{"title":"Bearer Auth","type":"string","isRequired":true,"description":"Your [Paragon User Token](/getting-started/installing-the-connect-sdk#setup) (JWT), which you can generate using your project's signing keys.","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"bearerAuth","name":"Authorization"}],"title":"bearerAuth"}]},"originalFileLocation":"agent-os/openapi/tools.json"},"subdomain":"paragon","siteName":"Paragon Documentation","title":"Run Tool - Paragon Documentation","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-10-29T04:53:18.135Z","originalFileLocation":"agent-os/tools/create-execution.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Run a tool on behalf of a Connected User.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Paragon Documentation\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003cmeta data-mint-head name=\"robots\" content=\"noindex\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/paragon/jEl23Mfv0t0lim0x/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/paragon/jEl23Mfv0t0lim0x/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/paragon/jEl23Mfv0t0lim0x/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/paragon/jEl23Mfv0t0lim0x/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/paragon/jEl23Mfv0t0lim0x/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/paragon/jEl23Mfv0t0lim0x/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/paragon/jEl23Mfv0t0lim0x/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/paragon/jEl23Mfv0t0lim0x/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/paragon/jEl23Mfv0t0lim0x/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Run Tool - Paragon Documentation\">\u003cmeta data-mint-head property=\"og:description\" content=\"Run a tool on behalf of a Connected User.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Paragon Documentation\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.useparagon.com/agent-os/tools/create-execution\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://paragon.mintlify.app/_mintlify/api/og/v2?division=Tools\u0026amp;title=Run+Tool\u0026amp;description=Run+a+tool+on+behalf+of+a+Connected+User.\u0026amp;theme=13788743c298c81ac0d08ae9\u0026amp;signature=280cd99897920b6f76996e57068a20db046bef58219c858f4467ba558ac35edb\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Run Tool - Paragon Documentation\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Run a tool on behalf of a Connected User.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://paragon.mintlify.app/_mintlify/api/og/v2?division=Tools\u0026amp;title=Run+Tool\u0026amp;description=Run+a+tool+on+behalf+of+a+Connected+User.\u0026amp;theme=13788743c298c81ac0d08ae9\u0026amp;signature=280cd99897920b6f76996e57068a20db046bef58219c858f4467ba558ac35edb\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/paragon/jEl23Mfv0t0lim0x/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Paragon Documentation\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#6645e6\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.useparagon.com/agent-os/tools/create-execution\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/agent-os/tools/create-execution.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.useparagon.com/#organization\",\"name\":\"Paragon Documentation\",\"url\":\"https://docs.useparagon.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/paragon/VsFfcYgo5-Qm6khT/logo/light.svg?fit=max\u0026auto=format\u0026n=VsFfcYgo5-Qm6khT\u0026q=85\u0026s=348909bc26f6451e89f4010d965f6e3f\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.useparagon.com#website\",\"name\":\"Paragon Documentation\",\"url\":\"https://docs.useparagon.com\",\"publisher\":{\"@id\":\"https://docs.useparagon.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.useparagon.com/agent-os/tools/create-execution#webpage\",\"url\":\"https://docs.useparagon.com/agent-os/tools/create-execution\",\"name\":\"Run Tool\",\"description\":\"Run a tool on behalf of a Connected User.\",\"dateModified\":\"2026-10-29T04:53:18.135Z\",\"isPartOf\":{\"@id\":\"https://docs.useparagon.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.useparagon.com/agent-os/tools/create-execution#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.useparagon.com/agent-os/tools/create-execution#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Tools\",\"item\":\"https://docs.useparagon.com/agent-os/tools/overview\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Run Tool\",\"item\":\"https://docs.useparagon.com/agent-os/tools/create-execution\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.useparagon.com/agent-os/tools/create-execution#apireference\",\"headline\":\"Run Tool\",\"name\":\"Run Tool\",\"description\":\"Run a tool on behalf of a Connected User.\",\"url\":\"https://docs.useparagon.com/agent-os/tools/create-execution\",\"mainEntityOfPage\":{\"@id\":\"https://docs.useparagon.com/agent-os/tools/create-execution#webpage\"},\"dateModified\":\"2026-10-29T04:53:18.135Z\",\"publisher\":{\"@id\":\"https://docs.useparagon.com/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.useparagon.com#website\"}}]}\u003c/script>","siteName":"Paragon Documentation","nav":{"global":null,"tabs":[{"tab":"Platform","pages":[{"title":"Platform","href":"/overview"}]},{"tab":"Agent OS","hidden":true,"groups":[{"group":"Agent OS","pages":[{"title":"Agent OS","sidebarTitle":"Overview","mode":"wide","description":"Build agents that can retrieve context, choose tools, and take action across your users' connected apps.","href":"/agent-os/overview"},{"title":"Getting Started","description":"Authenticate your users, send them a Setup Link, and make your first Context API and Tools API calls.","href":"/agent-os/getting-started"}]},{"group":"Context","pages":[{"title":"Context API","sidebarTitle":"Overview","description":"Search your users' synced content and read the text around a search result.","href":"/agent-os/context/overview"},{"title":"Create Setup Link","openapi":"agent-os/openapi/context.json POST /projects/{projectId}/setup-links","description":"Create a hosted link where a user connects the sources Agent OS can search.","href":"/agent-os/context/create-setup-link"},{"title":"Search Context","openapi":"agent-os/openapi/context.json POST /api/context/projects/{projectId}/search","description":"Search your users' synced content and return the best matching passages.","href":"/agent-os/context/search"},{"title":"Read Segment Context","openapi":"agent-os/openapi/context.json GET /api/context/projects/{projectId}/segments/{pointer}/context","description":"Read the text before and after a passage returned by search.","href":"/agent-os/context/read-segment"}]},{"group":"Tools","pages":[{"title":"Tools API","sidebarTitle":"Overview","description":"Give your agent the capabilities it needs to act across your users' connected apps.","href":"/agent-os/tools/overview"},{"title":"Search Tools","openapi":"agent-os/openapi/tools.json POST /api/tools/projects/{projectId}/tools/search","description":"Search the Paragon catalog for relevant Tools to use for a conversation turn.","href":"/agent-os/tools/search"},{"title":"Run Tool","openapi":"agent-os/openapi/tools.json POST /api/tools/projects/{projectId}/executions","href":"/agent-os/tools/create-execution"},{"title":"Get Result","openapi":"agent-os/openapi/tools.json GET /api/tools/projects/{projectId}/results/{resultId}","description":"Read the envelope for a stored tool result.","href":"/agent-os/tools/get-result"},{"title":"Get Result Rows","openapi":"agent-os/openapi/tools.json GET /api/tools/projects/{projectId}/results/{resultId}/rows","description":"Filter and page through records in a stored tool result.","href":"/agent-os/tools/get-result-rows"},{"title":"Get Result Content","openapi":"agent-os/openapi/tools.json GET /api/tools/projects/{projectId}/results/{resultId}/content","description":"Read a character slice of a text-shaped stored result.","href":"/agent-os/tools/get-result-content"},{"title":"Get Execution","openapi":"agent-os/openapi/tools.json GET /api/tools/projects/{projectId}/executions/{executionId}","description":"Read an execution, optionally waiting while it is still running.","href":"/agent-os/tools/get-execution"},{"title":"Cancel Execution","openapi":"agent-os/openapi/tools.json POST /api/tools/projects/{projectId}/executions/{executionId}/cancel","description":"Cancel a running execution.","href":"/agent-os/tools/cancel-execution"},{"title":"Get Tool","openapi":"agent-os/openapi/tools.json GET /api/tools/projects/{projectId}/tools/{intentName}","description":"Fetch one tool definition by its tool name.","href":"/agent-os/tools/get-tool"}]}]},{"tab":"Managed Sync","icon":"https://mintlify.s3.us-west-1.amazonaws.com/paragon/assets/sync-icon-light.svg","pages":[{"title":"Managed Sync","href":"/managed-sync/overview"}]},{"tab":"ActionKit","icon":"https://mintlify.s3.us-west-1.amazonaws.com/paragon/assets/actions-icon-light.svg","pages":[{"title":"ActionKit","href":"/actionkit/overview"}]},{"tab":"Workflows","icon":"https://mintlify.s3.us-west-1.amazonaws.com/paragon/assets/workflow-icon-light.svg","pages":[{"title":"Workflows","href":"/workflows/overview"}]},{"tab":"Integrations","pages":[{"title":"Integrations","href":"/resources/integrations"}]},{"tab":"API Reference","pages":[{"title":"API Reference","href":"/apis/api-reference"}]},{"tab":"Guides","menu":[{"item":"Home","pages":[{"title":"Home","href":"/guides"}]},{"item":"Authentication","groups":[{"group":"Authentication","pages":[{"title":"Authentication","href":"/tutorials/building-an-in-app-integrations-catalog"}]}],"global":{"anchors":[{"anchor":"Back to all guides","icon":"arrow-left","href":"/guides"}]}},{"item":"Deploying Integrations","groups":[{"group":"Deploying Integrations","pages":[{"title":"Deploying Integrations","href":"/knowledge-base/git-sync-missing-commits"}]}],"global":{"anchors":[{"anchor":"Back to all guides","icon":"arrow-left","href":"/guides"}]}},{"item":"Custom Integrations or Webhooks","groups":[{"group":"Custom Integrations or Webhooks","pages":[{"title":"Custom Integrations or Webhooks","href":"/knowledge-base/api-base-url-ip-403"}]}],"global":{"anchors":[{"anchor":"Back to all guides","icon":"arrow-left","href":"/guides"}]}},{"item":"Billing and Account Management","groups":[{"group":"Billing and Account Management","pages":[{"title":"Billing and Account Management","href":"/knowledge-base/email-invite-404"}]}],"global":{"anchors":[{"anchor":"Back to all guides","icon":"arrow-left","href":"/guides"}]}},{"item":"ActionKit","groups":[{"group":"ActionKit","pages":[{"title":"ActionKit","href":"/actionkit/actionkit-for-tool-calling"}]}],"global":{"anchors":[{"anchor":"Back to all guides","icon":"arrow-left","href":"/guides"}]}},{"item":"Workflows","groups":[{"group":"Workflows","pages":[{"title":"Workflows","href":"/tutorials/building-a-salesforce-integration"}]}],"global":{"anchors":[{"anchor":"Back to all guides","icon":"arrow-left","href":"/guides"}]}}],"pages":[{"title":"Guides","href":"/guides"}]},{"tab":"Release Notes","pages":[{"title":"Release Notes","href":"/changelog/product-updates"}]}]},"title":"Run Tool - Paragon Documentation","buildId":"dpl_EnxDqhjaNc9a8MVa833TGULPd9uJ","deploymentId":"dpl_EnxDqhjaNc9a8MVa833TGULPd9uJ","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-26-lDe7V.js","utils-CWQmgYtH.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-4-Aw3rSD.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-C2zjXYA5.js","snippetPresets-DFmpFA7C.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","ApiExamples-FJpQavWq.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-D_GvPF7k.js","shallow-Bs2ZB0NO.js","getApiPlaygroundDisplay-DCcqJJk-.js","CodeSnippet-DzDxawVe.js","CodeSnippets-aUr7fU-7.js","Page-CT9uE8Ip.js","getPastedJson-Y1fKsj_I.js","icon-DI4zTsDr.js","MethodPill-C0nDlmSQ.js","DuplicateIcon-NUXbx2nQ.js","createIcon-BdTHrPAi.js","DynamicMarkdown-CtpgKJwj.js","SectionHeading-B3x35tOt.js","axios-vUo_bRtp.js","Markdown-3OmurJMP.js","clsx-DMKzROTp.js","lib-DuNMoZ05.js","lib-B8HbPgcC.js","html-void-elements-mCSPHezU.js","dist-1ms6tsT-.js","katex-YMM-FMeD.js","marked.esm-CZWythHk.js","AssistantPageLink-Ke9xIMFx.js"]}