Starts an agent on a task and returns the run while it initializes. Each successful request creates a separate run. The agent continues independently of your HTTP connection.
Supply an agent configuration and instructions with targets, vulnerabilityIds, or both. A base such as tcell uses that pre-built agent’s defaults; supplied configuration fields replace the corresponding exposed defaults. Vulnerability IDs are resolved within your organization. Target scope is checked before execution.
The SDK serializes the Agent object into agent and converts task vulnerabilities into vulnerabilityIds. The run retains the resolved configuration even if the registered agent changes later.
POST
/
runs
curl --request POST \
--url https://api.antigen.sh/v1/runs \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"agent": {
"base": "tcell"
},
"task": {
"instructions": "Test the production API for authorization vulnerabilities.",
"targets": [
"api.example.com"
]
}
}
'
{
"id": "run_123",
"status": "creating",
"agent": {
"base": "tcell",
"model": "claude-opus-5-cyber",
"skills": [
"Check authorization when one account requests another account’s resources."
],
"guardrails": "Do not attempt denial of service.",
"tools": [
"asset_map",
"human_tasks"
]
},
"task": {
"instructions": "Test the production API for authorization vulnerabilities.",
"targets": [
"api.example.com"
]
},
"createdAt": "2026-09-13T10:00:00.000Z",
"updatedAt": "2026-09-13T10:00:00.000Z",
"error": null
}
{
"error": {
"code": "invalid_request",
"message": "Check the request fields and values."
}
}
{
"error": {
"code": "unauthorized",
"message": "Supply a valid API key or session token."
}
}
{
"error": {
"code": "forbidden",
"message": "Your role does not permit this operation, or the requested work is outside approved scope."
}
}
{
"error": {
"code": "rate_limited",
"message": "Retry after the interval in Retry-After."
}
}
Authorizations
ApiKeyAuthSessionAuth
x-api-key
string
header
required
API key from your organization, for CI pipelines and other automated systems. Supply the value directly, without a Bearer prefix. A key acts as an admin of its organization. When a request carries both a key and a session, the key is used.
Body
application/json
agent
object
required
An agent configuration. Supply a pre-built base, a model, or both. Omitted fields use the base configuration, or empty skills and guardrails with asset_map and human_tasks tools when no base is supplied. Supplied fields replace the corresponding values. A retrieved Agent can be passed directly; name and builtIn are response metadata and do not change execution.
Option 1
Option 2
Show child attributes
Example:
{ "base": "tcell" }
task
object
required
Option 1
Option 2
Show child attributes
Example:
{
"instructions": "Test the production API for authorization vulnerabilities.",
"targets": ["api.example.com"]
}
Response
Created.
id
string
required
Minimum string length: 1
status
enum<string>
required
Available options:
creating,
running,
stopped,
completed,
failed
agent
object
required
Show child attributes
Example:
{
"base": "tcell",
"model": "claude-opus-5-cyber",
"skills": [
"Check authorization when one account requests another account’s resources."
],
"guardrails": "Do not attempt denial of service.",
"tools": ["asset_map", "human_tasks"]
}
task
object
required
Option 1
Option 2
Show child attributes
Example:
{
"instructions": "Test the production API for authorization vulnerabilities.",
"targets": ["api.example.com"]
}
createdAt
string<date-time>
required
updatedAt
string<date-time>
required
error
string | null
required
Failure description when status is failed; otherwise null.
curl --request POST \
--url https://api.antigen.sh/v1/runs \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"agent": {
"base": "tcell"
},
"task": {
"instructions": "Test the production API for authorization vulnerabilities.",
"targets": [
"api.example.com"
]
}
}
'
{
"id": "run_123",
"status": "creating",
"agent": {
"base": "tcell",
"model": "claude-opus-5-cyber",
"skills": [
"Check authorization when one account requests another account’s resources."
],
"guardrails": "Do not attempt denial of service.",
"tools": [
"asset_map",
"human_tasks"
]
},
"task": {
"instructions": "Test the production API for authorization vulnerabilities.",
"targets": [
"api.example.com"
]
},
"createdAt": "2026-09-13T10:00:00.000Z",
"updatedAt": "2026-09-13T10:00:00.000Z",
"error": null
}
{
"error": {
"code": "invalid_request",
"message": "Check the request fields and values."
}
}
{
"error": {
"code": "unauthorized",
"message": "Supply a valid API key or session token."
}
}
{
"error": {
"code": "forbidden",
"message": "Your role does not permit this operation, or the requested work is outside approved scope."
}
}
{
"error": {
"code": "rate_limited",
"message": "Retry after the interval in Retry-After."
}
}
{"docsConfig":{"theme":"sequoia","$schema":"https://mintlify.com/docs.json","name":"Antigen Docs","description":"Build, integrate, and get help with Antigen.","colors":{"primary":"#E45912","light":"#E45912","dark":"#E45912"},"logo":{"light":"https://mintcdn.com/antigen/CwR9WHjkWEWJK1Tv/logo/antigen-lockup.svg?fit=max\u0026auto=format\u0026n=CwR9WHjkWEWJK1Tv\u0026q=85\u0026s=52ad3e0ee1a3fa20cf28dc112f76859c","dark":"https://mintcdn.com/antigen/CwR9WHjkWEWJK1Tv/logo/antigen-lockup.svg?fit=max\u0026auto=format\u0026n=CwR9WHjkWEWJK1Tv\u0026q=85\u0026s=52ad3e0ee1a3fa20cf28dc112f76859c","href":"https://antigen.sh"},"favicon":"https://mintcdn.com/antigen/xITFlKbisuJyvmpS/logo/favicon.png?fit=max\u0026auto=format\u0026n=xITFlKbisuJyvmpS\u0026q=85\u0026s=5456d18ff98c94fdd69c7e234163f9a0","appearance":{"default":"light","strict":false},"background":{"color":{"light":"#F8F8F7","dark":"#171310"}},"navbar":{"links":[{"href":"https://antigen.sh/login","label":"Log in"}],"primary":{"type":"button","label":"Get a demo","href":"https://cal.com/team/antigen/demo"}},"fonts":{"family":"Lay Grotesk","weight":400,"source":"fonts/lay-grotesk-regular.woff","format":"woff"},"icons":{"library":"lucide"},"styling":{"codeblocks":{"theme":{"light":"github-light","dark":"github-dark"}},"latex":false},"contextual":{"options":["copy","view","chatgpt","claude","perplexity","mcp","cursor","vscode"],"display":"header"},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"antigen","hasAudioNarration":false,"actualSubdomain":"antigen","customDomains":["docs.antigen.sh"],"gitSource":{"type":"github","owner":"antigenco","repo":"monorepo","deployBranch":"main","contentDirectory":"apps/docs","isPrivate":true,"mountPath":"","label":""},"entitlements":{"AI_CHAT":{"status":"DISABLED"}},"buildId":"6afde5f65dd594ac56e06289","clientVersion":"0.0.4227","searchFilterCounts":[{"language":"default","tag":"Docs","count":63},{"language":"default","tag":"Help","count":50},{"language":"default","tag":"API","count":48},{"language":"default","tag":"Endpoints","count":46},{"language":"default","tag":"Integrations","count":33},{"language":"default","tag":"Getting started and account","count":18},{"language":"default","tag":"Product guides","count":17},{"language":"default","tag":"SDK","count":15},{"language":"default","tag":"Support and policies","count":14},{"language":"default","tag":"Runs","count":13}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"/docs","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","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":"rbac-expansion","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":"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":"full-page-search","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":"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":"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":"turbopuffer-dual-write","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},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"treatment","enabled":true,"payload":{"type":"string","value":"treatment"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"privacy":{"consentBanner":{"enabled":true}},"googleFontsInlined":false},"customCss":[{"filePath":"style.css","href":"/docs/_mintlify/custom/antigen/640f881c86e5fd63/style.css"}]}
{"page":{"pagePath":"reference/endpoints/runs/start-a-run","slug":"/reference/endpoints/runs/start-a-run","pageMetadata":{"title":"Start a run","description":"Starts an agent on a task and returns the run while it initializes. Each successful request creates a separate run. The agent continues independently of your HTTP connection.\n\nSupply an agent configuration and instructions with targets, vulnerabilityIds, or both. A base such as tcell uses that pre-built agent’s defaults; supplied configuration fields replace the corresponding exposed defaults. Vulnerability IDs are resolved within your organization. Target scope is checked before execution.\n\nThe SDK serializes the Agent object into agent and converts task vulnerabilities into vulnerabilityIds. The run retains the resolved configuration even if the registered agent changes later.","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml post /runs","href":"/reference/endpoints/runs/start-a-run","autogeneratedByOpenApi":true},"description":{"compiledSource":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"Starts an agent on a task and returns the run while it initializes. Each successful request creates a separate run. The agent continues independently of your HTTP connection.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Supply an agent configuration and instructions with targets, vulnerabilityIds, or both. A base such as tcell uses that pre-built agent’s defaults; supplied configuration fields replace the corresponding exposed defaults. Vulnerability IDs are resolved within your organization. Target scope is checked before execution.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"The SDK serializes the Agent object into agent and converts task vulnerabilities into vulnerabilityIds. The run retains the resolved configuration even if the registered agent changes later.\"\n })]\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}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){return _jsx(_Fragment,{})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"codeStyling":{"theme":{"light":"github-light","dark":"github-dark"}},"config":{},"pageMetadata":{"title":"Start a run","description":"Starts an agent on a task and returns the run while it initializes. Each successful request creates a separate run. The agent continues independently of your HTTP connection.\n\nSupply an agent configuration and instructions with targets, vulnerabilityIds, or both. A base such as tcell uses that pre-built agent’s defaults; supplied configuration fields replace the corresponding exposed defaults. Vulnerability IDs are resolved within your organization. Target scope is checked before execution.\n\nThe SDK serializes the Agent object into agent and converts task vulnerabilities into vulnerabilityIds. The run retains the resolved configuration even if the registered agent changes later.","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml post /runs","href":"/reference/endpoints/runs/start-a-run","autogeneratedByOpenApi":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":["/docs/_mintlify/custom/antigen/cc095e5e7ecece8b/search.js","/docs/_mintlify/custom/antigen/8bf7f8dd7f27000a/copy-page-feedback.js","/docs/_mintlify/custom/antigen/1558908238dac6fe/theme-toggle.js","/docs/_mintlify/custom/antigen/e2f117ac7f724865/document-title.js","/docs/_mintlify/custom/antigen/57cb34dec7aceb16/consent-banner.js"],"openApiReferenceData":{"operation":{"tags":["Runs"],"summary":"Start a run","operationId":"createRun","description":"Starts an agent on a task and returns the run while it initializes. Each successful request creates a separate run. The agent continues independently of your HTTP connection.\n\nSupply an agent configuration and instructions with targets, vulnerabilityIds, or both. A base such as tcell uses that pre-built agent’s defaults; supplied configuration fields replace the corresponding exposed defaults. Vulnerability IDs are resolved within your organization. Target scope is checked before execution.\n\nThe SDK serializes the Agent object into agent and converts task vulnerabilities into vulnerabilityIds. The run retains the resolved configuration even if the registered agent changes later.","requestBody":"6b47f531-c1d2-426a-ba3c-13e23494b46d","responses":{"201":"53f647fb-3362-4893-b04e-2033bf2c5921","400":"c7d31f01-8261-4419-bee2-21c808f89321","401":"00630d29-c844-4f84-a300-9fc12a9e1c69","403":"58106b20-afb0-40b5-a9e2-153d33f580dd","429":"7511a1dc-0184-4a78-b521-04df7b6c3295"},"method":"post","type":"path","servers":["b5b675bf-48ec-4549-8ead-c1569b296831"],"security":["f3a4e5a9-8a26-4fb2-b482-fe082aeb900f","3a4dd338-134f-473c-8cfe-d7a36b7f407f"],"path":"/runs","baseUrlOptions":["https://api.antigen.sh/v1"],"title":"Start a run","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"agent":{"oneOf":[{"type":"object","description":"An agent configuration. Supply a pre-built base, a model, or both. Omitted fields use the base configuration, or empty skills and guardrails with asset_map and human_tasks tools when no base is supplied. Supplied fields replace the corresponding values. A retrieved Agent can be passed directly; name and builtIn are response metadata and do not change execution.","required":["base"],"example":{"base":"tcell"},"properties":{"base":{"type":"string","description":"Underlying pre-built agent. Its private instructions remain managed by Antigen. Use null to assemble an agent without a pre-built base.","enum":["tcell","triage-agent","remediation-agent"],"isRequired":true,"uniqueKey":"agent.oneOf.0.base","typeLabel":"enum\u003cstring>"},"model":{"type":"string","description":"Model ID from GET /models.","minLength":1,"uniqueKey":"agent.oneOf.0.model","typeLabel":"string"},"skills":{"type":"array","items":{"type":"string","uniqueKey":"agent.oneOf.0.skills.items.[INDEX]","typeLabel":"string"},"description":"Instruction strings. Send file contents, not file paths.","uniqueKey":"agent.oneOf.0.skills","typeLabel":"string[]"},"guardrails":{"type":"string","description":"Natural-language constraints on agent behavior.","uniqueKey":"agent.oneOf.0.guardrails","typeLabel":"string"},"tools":{"type":"array","items":{"type":"string","uniqueKey":"agent.oneOf.0.tools.items.[INDEX]","typeLabel":"string"},"description":"Names of tools available to the agent, such as asset_map and human_tasks.","uniqueKey":"agent.oneOf.0.tools","typeLabel":"string[]"}},"additionalProperties":false,"isRequired":true,"uniqueKey":"agent.oneOf.0","typeLabel":"object"},{"type":"object","description":"An agent configuration. Supply a pre-built base, a model, or both. Omitted fields use the base configuration, or empty skills and guardrails with asset_map and human_tasks tools when no base is supplied. Supplied fields replace the corresponding values. A retrieved Agent can be passed directly; name and builtIn are response metadata and do not change execution.","required":["model"],"example":{"base":"tcell"},"properties":{"model":{"type":"string","description":"Model ID from GET /models.","minLength":1,"isRequired":true,"uniqueKey":"agent.oneOf.1.model","typeLabel":"string"},"base":{"oneOf":[{"type":"string","enum":["tcell","triage-agent","remediation-agent",null],"description":"Underlying pre-built agent. Its private instructions remain managed by Antigen. Use null to assemble an agent without a pre-built base.","uniqueKey":"agent.oneOf.1.base.oneOf.0","typeLabel":"enum\u003cstring>"},{"type":"null","enum":["tcell","triage-agent","remediation-agent",null],"description":"Underlying pre-built agent. Its private instructions remain managed by Antigen. Use null to assemble an agent without a pre-built base.","uniqueKey":"agent.oneOf.1.base.oneOf.1","typeLabel":"null"}],"uniqueKey":"agent.oneOf.1.base","typeLabel":"enum\u003cstring> | null"},"skills":{"type":"array","items":{"type":"string","uniqueKey":"agent.oneOf.1.skills.items.[INDEX]","typeLabel":"string"},"description":"Instruction strings. Send file contents, not file paths.","uniqueKey":"agent.oneOf.1.skills","typeLabel":"string[]"},"guardrails":{"type":"string","description":"Natural-language constraints on agent behavior.","uniqueKey":"agent.oneOf.1.guardrails","typeLabel":"string"},"tools":{"type":"array","items":{"type":"string","uniqueKey":"agent.oneOf.1.tools.items.[INDEX]","typeLabel":"string"},"description":"Names of tools available to the agent, such as asset_map and human_tasks.","uniqueKey":"agent.oneOf.1.tools","typeLabel":"string[]"}},"additionalProperties":false,"isRequired":true,"uniqueKey":"agent.oneOf.1","typeLabel":"object"}],"isRequired":true,"uniqueKey":"agent","typeLabel":"object"},"task":{"oneOf":[{"type":"object","required":["instructions","targets"],"example":{"instructions":"Test the production API for authorization vulnerabilities.","targets":["api.example.com"]},"properties":{"targets":{"type":"array","items":{"type":"string","uniqueKey":"task.oneOf.0.targets.items.[INDEX]","typeLabel":"string"},"description":"Target values within your organization’s approved scope.","minItems":1,"isRequired":true,"uniqueKey":"task.oneOf.0.targets","typeLabel":"string[]"},"instructions":{"type":"string","description":"Work the agent should perform during this run.","minLength":1,"isRequired":true,"uniqueKey":"task.oneOf.0.instructions","typeLabel":"string"},"vulnerabilityIds":{"type":"array","items":{"type":"string","minLength":1,"uniqueKey":"task.oneOf.0.vulnerabilityIds.items.[INDEX]","typeLabel":"string"},"description":"Existing vulnerabilities in your organization. The API retrieves their current context.","uniqueKey":"task.oneOf.0.vulnerabilityIds","typeLabel":"string[]"}},"additionalProperties":false,"isRequired":true,"uniqueKey":"task.oneOf.0","typeLabel":"object"},{"type":"object","required":["instructions","vulnerabilityIds"],"example":{"instructions":"Test the production API for authorization vulnerabilities.","targets":["api.example.com"]},"properties":{"vulnerabilityIds":{"type":"array","items":{"type":"string","minLength":1,"uniqueKey":"task.oneOf.1.vulnerabilityIds.items.[INDEX]","typeLabel":"string"},"description":"Existing vulnerabilities in your organization. The API retrieves their current context.","minItems":1,"isRequired":true,"uniqueKey":"task.oneOf.1.vulnerabilityIds","typeLabel":"string[]"},"instructions":{"type":"string","description":"Work the agent should perform during this run.","minLength":1,"isRequired":true,"uniqueKey":"task.oneOf.1.instructions","typeLabel":"string"},"targets":{"type":"array","items":{"type":"string","uniqueKey":"task.oneOf.1.targets.items.[INDEX]","typeLabel":"string"},"description":"Target values within your organization’s approved scope.","uniqueKey":"task.oneOf.1.targets","typeLabel":"string[]"}},"additionalProperties":false,"isRequired":true,"uniqueKey":"task.oneOf.1","typeLabel":"object"}],"isRequired":true,"uniqueKey":"task","typeLabel":"object"}},"required":["agent","task"],"additionalProperties":false,"example":{"agent":{"base":"tcell"},"task":{"instructions":"Test the production API for authorization vulnerabilities.","targets":["api.example.com"]}},"uniqueKey":"","typeLabel":"object"},"examples":{"pentest":{"title":"pentest","value":{"agent":{"base":"tcell"},"task":{"instructions":"Test the production API for authorization vulnerabilities.","targets":["api.example.com"]}}},"custom":{"title":"custom","value":{"agent":{"model":"claude-opus-5-cyber","skills":["Check authorization across accounts."],"guardrails":"Do not attempt denial of service.","tools":["asset_map"]},"task":{"instructions":"Test the production API for authorization vulnerabilities.","targets":["api.example.com"]}}},"remediation":{"title":"remediation","value":{"agent":{"base":"remediation-agent"},"task":{"instructions":"Prepare a fix for the team to review.","vulnerabilityIds":["vuln_123"]}}}},"exampleType":"examples"}},"exampleType":"examples"},"responses":{"53f647fb-3362-4893-b04e-2033bf2c5921":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"isRequired":true,"uniqueKey":"id","typeLabel":"string"},"status":{"type":"string","enum":["creating","running","stopped","completed","failed"],"isRequired":true,"uniqueKey":"status","typeLabel":"enum\u003cstring>"},"agent":{"type":"object","properties":{"base":{"oneOf":[{"type":"string","enum":["tcell","triage-agent","remediation-agent",null],"description":"Underlying pre-built agent. Its private instructions remain managed by Antigen. Use null to assemble an agent without a pre-built base.","isRequired":true,"uniqueKey":"agent.base.oneOf.0","typeLabel":"enum\u003cstring>"},{"type":"null","enum":["tcell","triage-agent","remediation-agent",null],"description":"Underlying pre-built agent. Its private instructions remain managed by Antigen. Use null to assemble an agent without a pre-built base.","isRequired":true,"uniqueKey":"agent.base.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"agent.base","typeLabel":"enum\u003cstring> | null"},"model":{"type":"string","description":"Model ID from GET /models.","minLength":1,"isRequired":true,"uniqueKey":"agent.model","typeLabel":"string"},"skills":{"type":"array","items":{"type":"string","uniqueKey":"agent.skills.items.[INDEX]","typeLabel":"string"},"description":"Instruction strings. Send file contents, not file paths.","isRequired":true,"uniqueKey":"agent.skills","typeLabel":"string[]"},"guardrails":{"type":"string","description":"Natural-language constraints on agent behavior.","isRequired":true,"uniqueKey":"agent.guardrails","typeLabel":"string"},"tools":{"type":"array","items":{"type":"string","uniqueKey":"agent.tools.items.[INDEX]","typeLabel":"string"},"description":"Names of tools available to the agent, such as asset_map and human_tasks.","isRequired":true,"uniqueKey":"agent.tools","typeLabel":"string[]"}},"required":["base","model","skills","guardrails","tools"],"additionalProperties":false,"example":{"base":"tcell","model":"claude-opus-5-cyber","skills":["Check authorization when one account requests another account’s resources."],"guardrails":"Do not attempt denial of service.","tools":["asset_map","human_tasks"]},"isRequired":true,"uniqueKey":"agent","typeLabel":"object"},"task":{"oneOf":[{"type":"object","required":["instructions","targets"],"example":{"instructions":"Test the production API for authorization vulnerabilities.","targets":["api.example.com"]},"properties":{"targets":{"type":"array","items":{"type":"string","uniqueKey":"task.oneOf.0.targets.items.[INDEX]","typeLabel":"string"},"description":"Target values within your organization’s approved scope.","minItems":1,"isRequired":true,"uniqueKey":"task.oneOf.0.targets","typeLabel":"string[]"},"instructions":{"type":"string","description":"Work the agent should perform during this run.","minLength":1,"isRequired":true,"uniqueKey":"task.oneOf.0.instructions","typeLabel":"string"},"vulnerabilityIds":{"type":"array","items":{"type":"string","minLength":1,"uniqueKey":"task.oneOf.0.vulnerabilityIds.items.[INDEX]","typeLabel":"string"},"description":"Existing vulnerabilities in your organization. The API retrieves their current context.","uniqueKey":"task.oneOf.0.vulnerabilityIds","typeLabel":"string[]"}},"additionalProperties":false,"isRequired":true,"uniqueKey":"task.oneOf.0","typeLabel":"object"},{"type":"object","required":["instructions","vulnerabilityIds"],"example":{"instructions":"Test the production API for authorization vulnerabilities.","targets":["api.example.com"]},"properties":{"vulnerabilityIds":{"type":"array","items":{"type":"string","minLength":1,"uniqueKey":"task.oneOf.1.vulnerabilityIds.items.[INDEX]","typeLabel":"string"},"description":"Existing vulnerabilities in your organization. The API retrieves their current context.","minItems":1,"isRequired":true,"uniqueKey":"task.oneOf.1.vulnerabilityIds","typeLabel":"string[]"},"instructions":{"type":"string","description":"Work the agent should perform during this run.","minLength":1,"isRequired":true,"uniqueKey":"task.oneOf.1.instructions","typeLabel":"string"},"targets":{"type":"array","items":{"type":"string","uniqueKey":"task.oneOf.1.targets.items.[INDEX]","typeLabel":"string"},"description":"Target values within your organization’s approved scope.","uniqueKey":"task.oneOf.1.targets","typeLabel":"string[]"}},"additionalProperties":false,"isRequired":true,"uniqueKey":"task.oneOf.1","typeLabel":"object"}],"isRequired":true,"uniqueKey":"task","typeLabel":"object"},"createdAt":{"type":"string","format":"date-time","isRequired":true,"uniqueKey":"createdAt","typeLabel":"string\u003cdate-time>"},"updatedAt":{"type":"string","format":"date-time","isRequired":true,"uniqueKey":"updatedAt","typeLabel":"string\u003cdate-time>"},"error":{"oneOf":[{"type":"string","description":"Failure description when status is failed; otherwise null.","isRequired":true,"uniqueKey":"error.oneOf.0","typeLabel":"string"},{"type":"null","description":"Failure description when status is failed; otherwise null.","isRequired":true,"uniqueKey":"error.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"error","typeLabel":"string | null"}},"required":["id","status","agent","task","createdAt","updatedAt","error"],"additionalProperties":false,"example":{"id":"run_123","status":"running","agent":{"base":"tcell","model":"claude-opus-5-cyber","skills":["Check authorization when one account requests another account’s resources."],"guardrails":"Do not attempt denial of service.","tools":["asset_map","human_tasks"]},"task":{"instructions":"Test the production API for authorization vulnerabilities.","targets":["api.example.com"]},"createdAt":"2026-09-13T10:00:00.000Z","updatedAt":"2026-09-13T10:00:00.000Z","error":null},"uniqueKey":"","typeLabel":"object"},"example":{"id":"run_123","status":"creating","agent":{"base":"tcell","model":"claude-opus-5-cyber","skills":["Check authorization when one account requests another account’s resources."],"guardrails":"Do not attempt denial of service.","tools":["asset_map","human_tasks"]},"task":{"instructions":"Test the production API for authorization vulnerabilities.","targets":["api.example.com"]},"createdAt":"2026-09-13T10:00:00.000Z","updatedAt":"2026-09-13T10:00:00.000Z","error":null},"examples":{"Example":{"title":"Example","value":{"id":"run_123","status":"creating","agent":{"base":"tcell","model":"claude-opus-5-cyber","skills":["Check authorization when one account requests another account’s resources."],"guardrails":"Do not attempt denial of service.","tools":["asset_map","human_tasks"]},"task":{"instructions":"Test the production API for authorization vulnerabilities.","targets":["api.example.com"]},"createdAt":"2026-09-13T10:00:00.000Z","updatedAt":"2026-09-13T10:00:00.000Z","error":null}}},"exampleType":"examples"}},"exampleType":"examples"},"c7d31f01-8261-4419-bee2-21c808f89321":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable error code.","isRequired":true,"uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","description":"Description of the problem.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"}},"required":["code","message"],"additionalProperties":false,"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"invalid_request","message":"The target value is required."}},"uniqueKey":"","typeLabel":"object"},"example":{"error":{"code":"invalid_request","message":"Check the request fields and values."}},"examples":{"Example":{"title":"Example","value":{"error":{"code":"invalid_request","message":"Check the request fields and values."}}}},"exampleType":"examples"}},"exampleType":"examples"},"00630d29-c844-4f84-a300-9fc12a9e1c69":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable error code.","isRequired":true,"uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","description":"Description of the problem.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"}},"required":["code","message"],"additionalProperties":false,"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"invalid_request","message":"The target value is required."}},"uniqueKey":"","typeLabel":"object"},"example":{"error":{"code":"unauthorized","message":"Supply a valid API key or session token."}},"examples":{"Example":{"title":"Example","value":{"error":{"code":"unauthorized","message":"Supply a valid API key or session token."}}}},"exampleType":"examples"}},"exampleType":"examples"},"58106b20-afb0-40b5-a9e2-153d33f580dd":{"description":"Permission denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable error code.","isRequired":true,"uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","description":"Description of the problem.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"}},"required":["code","message"],"additionalProperties":false,"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"invalid_request","message":"The target value is required."}},"uniqueKey":"","typeLabel":"object"},"example":{"error":{"code":"forbidden","message":"Your role does not permit this operation, or the requested work is outside approved scope."}},"examples":{"Example":{"title":"Example","value":{"error":{"code":"forbidden","message":"Your role does not permit this operation, or the requested work is outside approved scope."}}}},"exampleType":"examples"}},"exampleType":"examples"},"7511a1dc-0184-4a78-b521-04df7b6c3295":{"description":"Too many requests","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable error code.","isRequired":true,"uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","description":"Description of the problem.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"}},"required":["code","message"],"additionalProperties":false,"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"invalid_request","message":"The target value is required."}},"uniqueKey":"","typeLabel":"object"},"example":{"error":{"code":"rate_limited","message":"Retry after the interval in Retry-After."}},"examples":{"Example":{"title":"Example","value":{"error":{"code":"rate_limited","message":"Retry after the interval in Retry-After."}}}},"exampleType":"examples"}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"exampleType":"examples"}},"security":{"f3a4e5a9-8a26-4fb2-b482-fe082aeb900f":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key from your organization, for CI pipelines and other automated systems. Supply the value directly, without a Bearer prefix. A key acts as an admin of its organization. When a request carries both a key and a session, the key is used.","scopes":[],"schemeName":"ApiKeyAuth"}},"3a4dd338-134f-473c-8cfe-d7a36b7f407f":{"SessionAuth":{"type":"http","scheme":"bearer","description":"Session token from `antigen login`, sent in the `Authorization` header with the `Bearer` scheme. The request acts as the signed-in member, with their own role in their organization. Sessions stop working when the member is deactivated.","scopes":[],"schemeName":"SessionAuth"}}},"servers":{"b5b675bf-48ec-4549-8ead-c1569b296831":{"url":"https://api.antigen.sh/v1"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key from your organization, for CI pipelines and other automated systems. Supply the value directly, without a Bearer prefix. A key acts as an admin of its organization. When a request carries both a key and a session, the key is used.","scopes":[],"schemeName":"ApiKeyAuth"},"schema":{"title":"x-api-key","type":"string","description":"API key from your organization, for CI pipelines and other automated systems. Supply the value directly, without a Bearer prefix. A key acts as an admin of its organization. When a request carries both a key and a session, the key is used.","isRequired":true,"typeLabel":"string","deprecated":false},"schemeName":"ApiKeyAuth","name":"x-api-key"}],"title":"ApiKeyAuth"},{"schemes":[{"scheme":{"type":"http","scheme":"bearer","description":"Session token from `antigen login`, sent in the `Authorization` header with the `Bearer` scheme. The request acts as the signed-in member, with their own role in their organization. Sessions stop working when the member is deactivated.","scopes":[],"schemeName":"SessionAuth"},"schema":{"title":"Bearer Auth","type":"string","isRequired":true,"description":"Session token from `antigen login`, sent in the `Authorization` header with the `Bearer` scheme. The request acts as the signed-in member, with their own role in their organization. Sessions stop working when the member is deactivated.","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"SessionAuth","name":"Authorization"}],"title":"SessionAuth"}]},"originalFileLocation":"reference/openapi.yaml"},"subdomain":"antigen","siteName":"Antigen Docs","title":"Start a run - Antigen Docs","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-11-13T23:19:42.744Z","originalFileLocation":"reference/endpoints/runs/start-a-run.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=\"light\"}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=\"Starts an agent on a task and returns the run while it initializes. Each successful request creates a separate run. The agent continues independently of your HTTP connection. Supply an agent configuration and instructions with targets, vulnerabilityIds, or both. A base such as tcell uses that pre-built agent’s defaults; supplied configuration fields replace the corresponding exposed defaults. Vulnerability IDs are resolved within your organization. Target scope is checked before execution. The SDK serializes the Agent object into agent and converts task vulnerabilities into vulnerabilityIds. The run retains the resolved configuration even if the registered agent changes later.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Antigen Docs\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/docs/mintlify-assets/_mintlify/favicons/antigen/hwn89cI3gFvZyaus/_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=\"/docs/mintlify-assets/_mintlify/favicons/antigen/hwn89cI3gFvZyaus/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/docs/mintlify-assets/_mintlify/favicons/antigen/hwn89cI3gFvZyaus/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/docs/mintlify-assets/_mintlify/favicons/antigen/hwn89cI3gFvZyaus/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/docs/mintlify-assets/_mintlify/favicons/antigen/hwn89cI3gFvZyaus/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/docs/mintlify-assets/_mintlify/favicons/antigen/hwn89cI3gFvZyaus/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/docs/mintlify-assets/_mintlify/favicons/antigen/hwn89cI3gFvZyaus/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/docs/mintlify-assets/_mintlify/favicons/antigen/hwn89cI3gFvZyaus/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/docs/mintlify-assets/_mintlify/favicons/antigen/hwn89cI3gFvZyaus/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Start a run - Antigen Docs\">\u003cmeta data-mint-head property=\"og:description\" content=\"Starts an agent on a task and returns the run while it initializes. Each successful request creates a separate run. The agent continues independently of your HTTP connection. Supply an agent configuration and instructions with targets, vulnerabilityIds, or both. A base such as tcell uses that pre-built agent’s defaults; supplied configuration fields replace the corresponding exposed defaults. Vulnerability IDs are resolved within your organization. Target scope is checked before execution. The SDK serializes the Agent object into agent and converts task vulnerabilities into vulnerabilityIds. The run retains the resolved configuration even if the registered agent changes later.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Antigen Docs\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.antigen.sh/docs/reference/endpoints/runs/start-a-run\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://antigen.mintlify.site/docs/_mintlify/api/og/v2?division=Runs\u0026amp;title=Start+a+run\u0026amp;description=Starts+an+agent+on+a+task+and+returns+the+run+while+it+initializes.+Each+successful+request+creates+a+separate+run.+The+agent+continues+independently+of+your+HT\u0026amp;theme=b6172b1861644199008c9fcf\u0026amp;signature=d55a56dceefa1dce99fe0b907f10adb960149414fd9e82e1a6789198ae9ecad1\">\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=\"Start a run - Antigen Docs\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Starts an agent on a task and returns the run while it initializes. Each successful request creates a separate run. The agent continues independently of your HTTP connection. Supply an agent configuration and instructions with targets, vulnerabilityIds, or both. A base such as tcell uses that pre-built agent’s defaults; supplied configuration fields replace the corresponding exposed defaults. Vulnerability IDs are resolved within your organization. Target scope is checked before execution. The SDK serializes the Agent object into agent and converts task vulnerabilities into vulnerabilityIds. The run retains the resolved configuration even if the registered agent changes later.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://antigen.mintlify.site/docs/_mintlify/api/og/v2?division=Runs\u0026amp;title=Start+a+run\u0026amp;description=Starts+an+agent+on+a+task+and+returns+the+run+while+it+initializes.+Each+successful+request+creates+a+separate+run.+The+agent+continues+independently+of+your+HT\u0026amp;theme=b6172b1861644199008c9fcf\u0026amp;signature=d55a56dceefa1dce99fe0b907f10adb960149414fd9e82e1a6789198ae9ecad1\">\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=\"/docs/mintlify-assets/_mintlify/favicons/antigen/hwn89cI3gFvZyaus/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Antigen Docs\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#E45912\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.antigen.sh/docs/reference/endpoints/runs/start-a-run\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/docs/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/docs/reference/endpoints/runs/start-a-run.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.antigen.sh/#organization\",\"name\":\"Antigen Docs\",\"url\":\"https://docs.antigen.sh\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/antigen/CwR9WHjkWEWJK1Tv/logo/antigen-lockup.svg?fit=max\u0026auto=format\u0026n=CwR9WHjkWEWJK1Tv\u0026q=85\u0026s=52ad3e0ee1a3fa20cf28dc112f76859c\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.antigen.sh/docs#website\",\"name\":\"Antigen Docs\",\"url\":\"https://docs.antigen.sh/docs\",\"publisher\":{\"@id\":\"https://docs.antigen.sh/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.antigen.sh/docs/reference/endpoints/runs/start-a-run#webpage\",\"url\":\"https://docs.antigen.sh/docs/reference/endpoints/runs/start-a-run\",\"name\":\"Start a run\",\"description\":\"Starts an agent on a task and returns the run while it initializes. Each successful request creates a separate run. The agent continues independently of your HTTP connection. Supply an agent configuration and instructions with targets, vulnerabilityIds, or both. A base such as tcell uses that pre-built agent’s defaults; supplied configuration fields replace the corresponding exposed defaults. Vulnerability IDs are resolved within your organization. Target scope is checked before execution. The SDK serializes the Agent object into agent and converts task vulnerabilities into vulnerabilityIds. The run retains the resolved configuration even if the registered agent changes later.\",\"dateModified\":\"2026-11-13T23:19:42.744Z\",\"isPartOf\":{\"@id\":\"https://docs.antigen.sh/docs#website\"},\"breadcrumb\":{\"@id\":\"https://docs.antigen.sh/docs/reference/endpoints/runs/start-a-run#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.antigen.sh/docs/reference/endpoints/runs/start-a-run#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Endpoints\",\"item\":\"https://docs.antigen.sh/docs/reference/endpoints/agents/list-agents\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Runs\",\"item\":\"https://docs.antigen.sh/docs/reference/endpoints/runs/list-runs\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"Start a run\",\"item\":\"https://docs.antigen.sh/docs/reference/endpoints/runs/start-a-run\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.antigen.sh/docs/reference/endpoints/runs/start-a-run#apireference\",\"headline\":\"Start a run\",\"name\":\"Start a run\",\"description\":\"Starts an agent on a task and returns the run while it initializes. Each successful request creates a separate run. The agent continues independently of your HTTP connection. Supply an agent configuration and instructions with targets, vulnerabilityIds, or both. A base such as tcell uses that pre-built agent’s defaults; supplied configuration fields replace the corresponding exposed defaults. Vulnerability IDs are resolved within your organization. Target scope is checked before execution. The SDK serializes the Agent object into agent and converts task vulnerabilities into vulnerabilityIds. The run retains the resolved configuration even if the registered agent changes later.\",\"url\":\"https://docs.antigen.sh/docs/reference/endpoints/runs/start-a-run\",\"mainEntityOfPage\":{\"@id\":\"https://docs.antigen.sh/docs/reference/endpoints/runs/start-a-run#webpage\"},\"dateModified\":\"2026-11-13T23:19:42.744Z\",\"publisher\":{\"@id\":\"https://docs.antigen.sh/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.antigen.sh/docs#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Antigen Docs\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Antigen Docs\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/docs/reference/endpoints/runs/start-a-run.md","siteName":"Antigen Docs","nav":{"global":null,"tabs":[{"tab":"Docs","pages":[{"title":"Docs","href":""}]},{"tab":"API","groups":[{"group":"Getting started","pages":[{"title":"Overview","href":"/reference"},{"title":"Webhook events","href":"/reference/webhooks"}]},{"group":"Endpoints","pages":[{"group":"Agents","pages":[{"title":"List agents","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml get /agents","href":"/reference/endpoints/agents/list-agents"},{"title":"Register an agent","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml post /agents","href":"/reference/endpoints/agents/register-an-agent"},{"title":"Get an agent","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml get /agents/{name}","href":"/reference/endpoints/agents/get-an-agent"},{"title":"Update an agent","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml patch /agents/{name}","href":"/reference/endpoints/agents/update-an-agent"}]},{"group":"Models","pages":[{"title":"List models","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml get /models","href":"/reference/endpoints/models/list-models"}]},{"group":"Targets","pages":[{"title":"List targets","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml get /targets","href":"/reference/endpoints/targets/list-targets"},{"title":"Submit a target","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml post /targets","href":"/reference/endpoints/targets/submit-a-target"},{"title":"Get a target","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml get /targets/{id}","href":"/reference/endpoints/targets/get-a-target"},{"title":"Update a target","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml patch /targets/{id}","href":"/reference/endpoints/targets/update-a-target"}]},{"group":"Runs","pages":[{"title":"List runs","description":"Returns runs in your organization. Filters apply together. Each result contains the agent configuration captured at launch and the task being performed.","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml get /runs","href":"/reference/endpoints/runs/list-runs"},{"title":"Start a run","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml post /runs","href":"/reference/endpoints/runs/start-a-run"},{"title":"Get a run","description":"Returns current status, the captured agent configuration, task, and failure details when present. Use this endpoint to check whether background work has completed.","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml get /runs/{id}","href":"/reference/endpoints/runs/get-a-run"},{"title":"Stream run events","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml get /runs/{id}/events","href":"/reference/endpoints/runs/stream-run-events"},{"title":"Steer a run","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml post /runs/{id}/steer","href":"/reference/endpoints/runs/steer-a-run"},{"title":"Stop a run","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml post /runs/{id}/stop","href":"/reference/endpoints/runs/stop-a-run"},{"title":"Resume a run","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml post /runs/{id}/resume","href":"/reference/endpoints/runs/resume-a-run"}]},{"group":"Vulnerabilities","pages":[{"title":"List vulnerabilities","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml get /vulnerabilities","href":"/reference/endpoints/vulnerabilities/list-vulnerabilities"},{"title":"Get a vulnerability","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml get /vulnerabilities/{id}","href":"/reference/endpoints/vulnerabilities/get-a-vulnerability"},{"title":"Update a vulnerability","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml patch /vulnerabilities/{id}","href":"/reference/endpoints/vulnerabilities/update-a-vulnerability"},{"title":"Push a vulnerability to a tracker","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml post /vulnerabilities/{id}/tracker-issue","href":"/reference/endpoints/vulnerabilities/push-a-vulnerability-to-a-tracker"}]},{"group":"Evidence","pages":[{"title":"List evidence","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml get /evidence","href":"/reference/endpoints/evidence/list-evidence"},{"title":"Get evidence","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml get /evidence/{id}","href":"/reference/endpoints/evidence/get-evidence"},{"title":"Download evidence","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml get /evidence/{id}/content","href":"/reference/endpoints/evidence/download-evidence"}]},{"group":"Reports","pages":[{"title":"List reports","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml get /reports","href":"/reference/endpoints/reports/list-reports"},{"title":"Get a report","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml get /reports/{id}","href":"/reference/endpoints/reports/get-a-report"},{"title":"Download a report","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml get /reports/{id}/content","href":"/reference/endpoints/reports/download-a-report"}]},{"group":"Human tasks","pages":[{"title":"List human tasks","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml get /human-tasks","href":"/reference/endpoints/human-tasks/list-human-tasks"},{"title":"Create a human task","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml post /human-tasks","href":"/reference/endpoints/human-tasks/create-a-human-task"},{"title":"Get a human task","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml get /human-tasks/{id}","href":"/reference/endpoints/human-tasks/get-a-human-task"},{"title":"Update a human task","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml patch /human-tasks/{id}","href":"/reference/endpoints/human-tasks/update-a-human-task"}]},{"group":"Hooks","pages":[{"title":"List hooks","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml get /hooks","href":"/reference/endpoints/hooks/list-hooks"},{"title":"Register a webhook","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml post /hooks","href":"/reference/endpoints/hooks/register-a-webhook"},{"title":"Get a hook","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml get /hooks/{id}","href":"/reference/endpoints/hooks/get-a-hook"},{"title":"Remove a webhook","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml delete /hooks/{id}","href":"/reference/endpoints/hooks/remove-a-webhook"},{"title":"Update a hook","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml patch /hooks/{id}","href":"/reference/endpoints/hooks/update-a-hook"}]},{"group":"Asset Map","pages":[{"title":"Get a graph","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml get /asset-map","href":"/reference/endpoints/asset-map/get-a-graph"},{"title":"Query the graph","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml post /asset-map/query","href":"/reference/endpoints/asset-map/query-the-graph"}]},{"group":"Integrations","pages":[{"title":"List integrations","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml get /integrations","href":"/reference/endpoints/integrations/list-integrations"},{"title":"Get an integration","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml get /integrations/{id}","href":"/reference/endpoints/integrations/get-an-integration"},{"title":"Disconnect an integration","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml delete /integrations/{id}","href":"/reference/endpoints/integrations/disconnect-an-integration"}]},{"group":"Team","pages":[{"title":"List team members","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml get /team","href":"/reference/endpoints/team/list-team-members"}]},{"group":"API keys","pages":[{"title":"List API keys","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml get /api-keys","href":"/reference/endpoints/api-keys/list-api-keys"},{"title":"Create an API key","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml post /api-keys","href":"/reference/endpoints/api-keys/create-an-api-key"},{"title":"Revoke an API key","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml delete /api-keys/{id}","href":"/reference/endpoints/api-keys/revoke-an-api-key"}]},{"group":"Account","pages":[{"title":"Get the caller","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml get /me","href":"/reference/endpoints/account/get-the-caller"},{"title":"Sign out","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml delete /session","href":"/reference/endpoints/account/sign-out"}]}]}]},{"tab":"Help","directory":"card","pages":[{"title":"Help","href":"/help"}]}]},"basePath":"","title":"Start a run - Antigen Docs","deploymentId":"dpl_2MqcLy8smQrrovUehgcZEsoo1tJX","buildId":"dpl_2MqcLy8smQrrovUehgcZEsoo1tJX","dynamics":["c2aa737661","b0f84f53ff","a9bb46feb3","2b790eda92"],"chunks":["OpenApiReferenceProvider-DyP0AOE1.js","snippetPresets-CuYPAUIG.js","utils-ez5j6NBT.js","style-to-object-BY3JEAdk.js","utils-DG4aeUOF.js","v4-DIgz8zy6.js","addUniqueKeysToSchema-DFhcMUrP.js","conditional-requirements-CFM0id0Q.js","cloneDeep-ByDTqllG.js","_Uint8Array-CJ2WjX_H.js","isObject-FP1Yky1u.js","Page-CInwEL5w.js","CodeSnippet-CCk6UVRR.js","DynamicMarkdown-CU5QIokU.js","SectionHeading-BoT1NwPU.js","icon-MsvNhD56.js","ApiExamples-fyn9sMD9.js","usePlaygroundInputsStore-Bf0N_Y6L.js","shallow-CnU26VTn.js","isEqual-OWIKZzop.js","CodeSnippets-CZ9-M31v.js","getApiPlaygroundDisplay-BUw5JwZB.js","MethodPill-CC7p0-fp.js","getPastedJson-BOWYR2ND.js","DuplicateIcon-DOWJyC1b.js","createIcon-BsNyCaLY.js","axios-CsQoIw0U.js","Markdown-L0uigQE0.js","AssistantPageLink-Cur5OU4v.js","dist-CLdzWocy.js","lib-DMeTj1gb.js","lib-B8HbPgcC.js","katex-Dbtb6Wk7.js","html-void-elements-mCSPHezU.js","marked.esm-CZWythHk.js"]}