Creates an empty draft run for a custom agent. A draft dials nothing: attach contacts, then launch. Contacts are deliberately not accepted here - a retried create would otherwise leave a second draft holding the same list, and that draft is exactly the thing someone launches later ‘to be safe’.
You cannot pass contacts to this endpoint, and that is a deliberate safety property rather than an omission.If create took a contact list, a request that timed out after the server had committed would leave you unable to tell whether it worked. Retrying would produce a second draft holding the same list — dialling nothing, but sitting there, launchable. An orphan holding 500 real contacts is exactly the thing someone finds later and launches “to be safe”, and then every one of those people is called twice.A retried create here leaves an empty draft instead. It holds nothing, so there is nothing to launch by mistake. Attach is idempotent by construction, so the second request is safe to repeat too.
This is why there is no Idempotency-Key header on this API. The one endpoint that would
have needed it does not need it once create is empty.
A run is the batch form of a custom agent’s conversation, so the hiring focuses (SCREENING, OUTREACH, LANGUAGE_TEST, GENERIC) cannot back one. A non-custom agent is a 422.The agent must also be in your own company. One that is not returns 404 rather than 403 — the API does not confirm that a resource you cannot reach exists.
const run = await fetch("https://api.instaview.sk/runs", { method: "POST", headers: { Authorization: `Bearer ${process.env.INSTAVIEW_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ name: "Q3 product follow-ups", agentId: "agent-uuid" }), signal: AbortSignal.timeout(10_000),});if (!run.ok) { throw new Error(`Creating the run failed: ${run.status} ${run.statusText}`);}
The company comes from your API key, never from the body. An ATS key names the child company with the companyIdquery parameter; a companyId in the body is rejected outright rather than quietly ignored, so a caller who thought they were targeting another company finds out.
Why a scheduled run did not start at its time, or null. A scheduled launch is re-admitted against billing when it fires, and a refusal then has no request to answer - it is reported here instead. The run stays SCHEDULED and is retried, so resolving the cause is enough to make it go.
Example:
"Insufficient minutes available to schedule 10 interviews (50 minutes total). Please purchase additional minutes."
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"InstaView API","colors":{"primary":"#2741F9","light":"#4D5FFF","dark":"#1D34C4"},"logo":{"light":"https://mintcdn.com/instaview/srYC_WLR3UAwt0PY/logo/light.svg?fit=max\u0026auto=format\u0026n=srYC_WLR3UAwt0PY\u0026q=85\u0026s=a941bc948e20b3503a55e49b4438bfd8","dark":"https://mintcdn.com/instaview/srYC_WLR3UAwt0PY/logo/dark.svg?fit=max\u0026auto=format\u0026n=srYC_WLR3UAwt0PY\u0026q=85\u0026s=fbf32075feea3b5f404b1aef04c449ea"},"favicon":"https://mintcdn.com/instaview/srYC_WLR3UAwt0PY/favicon.svg?fit=max\u0026auto=format\u0026n=srYC_WLR3UAwt0PY\u0026q=85\u0026s=1499b591dcea46419afceafb5b77004e","api":{"playground":{}},"navbar":{"links":[{"href":"https://support.instaview.sk","label":"Support"}],"primary":{"type":"button","label":"Dashboard","href":"https://app.instaview.sk"}},"footer":{"socials":{"github":"https://github.com/StarIC-s-r-o","linkedin":"https://www.linkedin.com/company/instaviewai"}},"contextual":{"options":["copy","view","chatgpt","claude","perplexity","mcp","cursor","vscode"],"display":"header"},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"instaview","hasAudioNarration":false,"actualSubdomain":"instaview","customDomains":["docs.instaview.sk"],"gitSource":{"type":"github","owner":"staric-s-r-o","repo":"instaview","deployBranch":"main","contentDirectory":"apps/docs","isPrivate":true,"mountPath":"","label":""},"chroma":{"liveDeploymentHistoryId":"6adb630a25769d6ebcdc21d7","collectionId":"9e3238e9-e795-4633-9eb1-2fa50fb2b100","schemaVersion":"v3","latestBuiltDeploymentHistoryId":"6adb630a25769d6ebcdc21d7"},"entitlements":{},"buildId":"6adb630a25769d6ebcdc21d7","clientVersion":"0.0.3965","searchFilterCounts":[{"language":"default","tag":"API Reference","count":75},{"language":"default","tag":"Documentation","count":20},{"language":"default","tag":"Changelog","count":13},{"language":"default","tag":"Runs","count":10},{"language":"default","tag":"2026","count":10},{"language":"default","tag":"Resources","count":9},{"language":"default","tag":"Agents","count":8},{"language":"default","tag":"Conversations","count":8},{"language":"default","tag":"Sourcing","count":8},{"language":"default","tag":"Webhooks","count":7}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableAskAiSearchBar":true},"hasChatPermissions":false,"hasWebMcpPermissions":false,"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":"editor-v7-file-tree","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":"pause-universal-search-reconcile","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":"per-site-search-delta","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":"editor-private-page-search","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":"editor-nav-generations","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":"editor-agent-model-picker","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":"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}],"isAtlas":false,"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"api-reference/runs/create-run","slug":"/api-reference/runs/create-run","pageMetadata":{"title":"Create Run","openapi":"POST /runs","description":"Creates an empty draft run for a custom agent. A draft dials nothing: attach contacts, then launch. Contacts are deliberately not accepted here - a retried create would otherwise leave a second draft holding the same list, and that draft is exactly the thing someone launches later 'to be safe'.","href":"/api-reference/runs/create-run"},"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: \"Creates an empty draft run for a custom agent. A draft dials nothing: attach contacts, then launch. Contacts are deliberately not accepted here - a retried create would otherwise leave a second draft holding the same list, and that draft is exactly the thing someone launches later ‘to be safe’.\"\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`,pre:`pre`,span:`span`,strong:`strong`,ul:`ul`,..._provideComponents(),...props.components},{Card,CardGroup,CodeBlock,Heading,Info}=_components;if(!Card)_missingMdxReference(`Card`,true);if(!CardGroup)_missingMdxReference(`CardGroup`,true);if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Info)_missingMdxReference(`Info`,true);return _jsxs(_Fragment,{children:[_jsx(_components.p,{children:`Creates an empty draft run for a custom agent.`}),`\n`,_jsx(Heading,{level:`2`,id:`overview`,children:`Overview`}),`\n`,_jsx(_components.p,{children:`A run is one agent working through a list of contacts. Building one is three steps, and none of them can call anybody twice:`}),`\n`,_jsx(CodeBlock,{numberOfLines:`4`,language:`text`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`text`,children:_jsxs(_components.code,{language:`text`,numberOfLines:`4`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`POST /runs → an empty draft`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`POST /runs/{id}/contacts → add contacts (idempotent)`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`POST /runs/{id}/launch → one conversation per contact`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{})})]})})}),`\n`,_jsx(_components.p,{children:`A draft dials nothing. Nothing is queued and nobody is called until you launch it.`}),`\n`,_jsx(Heading,{level:`2`,id:`contacts-are-not-accepted-here-on-purpose`,children:`Contacts are not accepted here, on purpose`}),`\n`,_jsx(_components.p,{children:`You cannot pass contacts to this endpoint, and that is a deliberate safety property rather than an omission.`}),`\n`,_jsxs(_components.p,{children:[`If create took a contact list, a request that timed out after the server had committed would leave you unable to tell whether it worked. Retrying would produce a `,_jsx(_components.strong,{children:`second draft holding the same list`}),` — dialling nothing, but sitting there, launchable. An orphan holding 500 real contacts is exactly the thing someone finds later and launches “to be safe”, and then every one of those people is called twice.`]}),`\n`,_jsxs(_components.p,{children:[`A retried create here leaves an empty draft instead. It holds nothing, so there is nothing to launch by mistake. `,_jsx(_components.a,{href:`/api-reference/runs/attach-run-contacts`,children:`Attach`}),` is idempotent by construction, so the second request is safe to repeat too.`]}),`\n`,_jsx(Info,{children:_jsxs(_components.p,{children:[`This is why there is no `,_jsx(_components.code,{children:`Idempotency-Key`}),` header on this API. The one endpoint that would\nhave needed it does not need it once create is empty.`]})}),`\n`,_jsx(Heading,{level:`2`,id:`the-agent-must-be-a-custom-agent`,children:`The agent must be a custom agent`}),`\n`,_jsxs(_components.p,{children:[`A run is the batch form of a `,_jsx(_components.a,{href:`/api-reference/agents/create-agent#custom-agents`,children:`custom agent’s`}),` conversation, so the hiring focuses (`,_jsx(_components.code,{children:`SCREENING`}),`, `,_jsx(_components.code,{children:`OUTREACH`}),`, `,_jsx(_components.code,{children:`LANGUAGE_TEST`}),`, `,_jsx(_components.code,{children:`GENERIC`}),`) cannot back one. A non-custom agent is a `,_jsx(_components.code,{children:`422`}),`.`]}),`\n`,_jsxs(_components.p,{children:[`The agent must also be in your own company. One that is not returns `,_jsx(_components.code,{children:`404`}),` rather than `,_jsx(_components.code,{children:`403`}),` — the API does not confirm that a resource you cannot reach exists.`]}),`\n`,_jsx(Heading,{level:`2`,id:`basic-usage`,children:`Basic Usage`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`13`,language:`javascript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`javascript`,children:_jsxs(_components.code,{language:`javascript`,numberOfLines:`13`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`const`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#4FC1FF`},children:` run`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` =`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` await`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:` fetch`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"https://api.instaview.sk/runs\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` method:`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"POST\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` headers:`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` Authorization:`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:\" `Bearer \"}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#569CD6`},children:\"${\"}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`process`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`env`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#4FC1FF`},children:`INSTAVIEW_API_KEY`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#569CD6`},children:`}`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:\"`\"}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"Content-Type\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`:`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"application/json\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` },`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` body:`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#4FC1FF`},children:` JSON`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`stringify`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`({ `}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`name:`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"Q3 product follow-ups\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`agentId:`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"agent-uuid\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }),`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` signal:`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` AbortSignal`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`timeout`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`10_000`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`),`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`});`})}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`if`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` (`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`!`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`run`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`ok`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`) {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` throw`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` new`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:` Error`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:\"`Creating the run failed: \"}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#569CD6`},children:\"${\"}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`run`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`status`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#569CD6`},children:`}`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#569CD6`},children:\" ${\"}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`run`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`statusText`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#569CD6`},children:`}`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:\"`\"}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`);`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`The company comes from your API key, never from the body. An ATS key names the child company with the `,_jsx(_components.code,{children:`companyId`}),` `,_jsx(_components.strong,{children:`query parameter`}),`; a `,_jsx(_components.code,{children:`companyId`}),` in the body is rejected outright rather than quietly ignored, so a caller who thought they were targeting another company finds out.`]}),`\n`,_jsx(Heading,{level:`2`,id:`response`,children:`Response`}),`\n`,_jsxs(_components.p,{children:[`The new run, in the same shape `,_jsx(_components.a,{href:`/api-reference/runs/get-run`,children:`Get Run`}),` returns — with an all-zero aggregate, because it has produced nothing yet:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`18`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`18`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"id\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"789e0123-e45b-67d8-a901-234567890123\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"name\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Q3 product follow-ups\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"agentId\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"456e7890-e12b-34d5-a678-901234567890\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"status\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"DRAFT\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"progress\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"total\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`0`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"queued\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`0`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"inProgress\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`0`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"completed\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`0`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"failed\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`0`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"cancelled\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`0`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"unreachable\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`0`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"completion\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`0`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` },`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"createdAt\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"2026-08-29T09:00:00Z\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"updatedAt\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"2026-08-29T09:00:00Z\"`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsx(Heading,{level:`2`,id:`error-scenarios`,children:`Error Scenarios`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`404 Not Found`}),`: the agent does not exist, or belongs to another company`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`422 Unprocessable Entity`}),`: the agent is not a custom agent`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`400 Bad Request`}),`: the body carries a field this endpoint does not accept, `,_jsx(_components.code,{children:`companyId`}),` included`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`403 Forbidden`}),`: the API key does not hold `,_jsx(_components.code,{children:`write:runs`})]}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`related-resources`,children:`Related Resources`}),`\n`,_jsxs(CardGroup,{cols:2,children:[_jsx(Card,{title:`Attach Contacts`,icon:`user-plus`,href:`/api-reference/runs/attach-run-contacts`,children:_jsx(_components.p,{children:`Add the people this run will call`})}),_jsx(Card,{title:`Launch Run`,icon:`play`,href:`/api-reference/runs/launch-run`,children:_jsx(_components.p,{children:`Fan the draft out into conversations`})}),_jsx(Card,{title:`Runs Resource Guide`,icon:`layer-group`,href:`/guides/resources/runs`,children:_jsx(_components.p,{children:`How a run batches conversations`})}),_jsx(Card,{title:`Create Agent`,icon:`robot`,href:`/api-reference/agents/create-agent`,children:_jsx(_components.p,{children:`Build the custom agent a run needs`})})]})]})}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":"Create Run","openapi":"POST /runs","description":"Creates an empty draft run for a custom agent. A draft dials nothing: attach contacts, then launch. Contacts are deliberately not accepted here - a retried create would otherwise leave a second draft holding the same list, and that draft is exactly the thing someone launches later 'to be safe'.","href":"/api-reference/runs/create-run"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Overview","slug":"overview","depth":2,"children":[]},{"title":"Contacts are not accepted here, on purpose","slug":"contacts-are-not-accepted-here-on-purpose","depth":2,"children":[]},{"title":"The agent must be a custom agent","slug":"the-agent-must-be-a-custom-agent","depth":2,"children":[]},{"title":"Basic Usage","slug":"basic-usage","depth":2,"children":[]},{"title":"Response","slug":"response","depth":2,"children":[]},{"title":"Error Scenarios","slug":"error-scenarios","depth":2,"children":[]},{"title":"Related Resources","slug":"related-resources","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"description":"Creates an empty draft run for a custom agent. A draft dials nothing: attach contacts, then launch. Contacts are deliberately not accepted here - a retried create would otherwise leave a second draft holding the same list, and that draft is exactly the thing someone launches later 'to be safe'.","operationId":"PublicRunsController_createRun_v1","parameters":["7902562b-4c29-44fc-a99c-a71b4cecf650"],"requestBody":"4b7439b1-71ef-40ed-a0df-b27ed76b8ecc","responses":{"201":"eedaeeaf-4e4a-48c3-8c85-684cb1e035d3","422":"fbbbae8f-613d-484c-9b78-9df7935432c4"},"security":["ec16b59f-6a3a-49b1-adc2-be794652fb7a"],"summary":"Create run","tags":["Runs"],"method":"post","type":"path","servers":["fefe9da2-a252-4644-8424-0eaff357a7a8"],"path":"/runs","baseUrlOptions":["https://api.instaview.sk"],"title":"Create run","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{"7902562b-4c29-44fc-a99c-a71b4cecf650":{"name":"companyId","required":false,"in":"query","description":"Required for ATS API keys to specify which company to access. Ignored for standard company API keys.","schema":{"type":"string","isRequired":false,"description":"Required for ATS API keys to specify which company to access. Ignored for standard company API keys.","uniqueKey":"","typeLabel":"string"}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name for the run","example":"Q3 product follow-ups","minLength":2,"maxLength":120,"isRequired":true,"uniqueKey":"name","typeLabel":"string"},"agentId":{"type":"string","format":"uuid","description":"The custom agent this run dials with. Must be a custom (Agent Designer) agent in the same company.","example":"456e7890-e12b-34d5-a678-901234567890","isRequired":true,"uniqueKey":"agentId","typeLabel":"string\u003cuuid>"}},"required":["name","agentId"],"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"name":"Q3 product follow-ups","agentId":"456e7890-e12b-34d5-a678-901234567890"}}},"exampleType":"generated"}},"exampleType":"generated"},"responses":{"eedaeeaf-4e4a-48c3-8c85-684cb1e035d3":{"description":"Run created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Run ID","example":"789e0123-e45b-67d8-a901-234567890123","isRequired":true,"uniqueKey":"id","typeLabel":"string\u003cuuid>"},"name":{"type":"string","description":"Name of the run","example":"Q3 product follow-ups","isRequired":true,"uniqueKey":"name","typeLabel":"string"},"agentId":{"type":"string","format":"uuid","description":"The agent this run dials with","example":"456e7890-e12b-34d5-a678-901234567890","isRequired":true,"uniqueKey":"agentId","typeLabel":"string\u003cuuid>"},"status":{"type":"string","description":"Lifecycle status. A `DRAFT` run has dialled nothing yet; `COMPLETED` is not terminal, because attaching a contact to a finished run reopens it to `RUNNING`.","enum":["DRAFT","SCHEDULED","RUNNING","PAUSED","COMPLETED","CANCELLED"],"example":"RUNNING","isRequired":true,"uniqueKey":"status","typeLabel":"enum\u003cstring>"},"progress":{"type":"object","description":"Aggregate progress across the run's conversations. Every conversation lands in exactly one bucket, so the six counts sum to `total`.","required":["total","queued","inProgress","completed","failed","cancelled","unreachable","completion"],"properties":{"total":{"type":"number","description":"Conversations this run has produced","example":42,"isRequired":true,"uniqueKey":"progress.total","typeLabel":"number"},"queued":{"type":"number","description":"Queued, not yet dialled","example":30,"isRequired":true,"uniqueKey":"progress.queued","typeLabel":"number"},"inProgress":{"type":"number","description":"Ringing or connected right now","example":3,"isRequired":true,"uniqueKey":"progress.inProgress","typeLabel":"number"},"completed":{"type":"number","description":"Finished conversations","example":8,"isRequired":true,"uniqueKey":"progress.completed","typeLabel":"number"},"failed":{"type":"number","description":"Conversations that failed","example":1,"isRequired":true,"uniqueKey":"progress.failed","typeLabel":"number"},"cancelled":{"type":"number","description":"Conversations that were cancelled","example":0,"isRequired":true,"uniqueKey":"progress.cancelled","typeLabel":"number"},"unreachable":{"type":"number","description":"Contacts whose retry budget was spent without the call ever connecting","example":0,"isRequired":true,"uniqueKey":"progress.unreachable","typeLabel":"number"},"completion":{"type":"number","description":"Fraction of conversations in a terminal state (completed + failed + cancelled + unreachable), 0 to 1. `0` on a run that has produced nothing yet.","example":0.21,"isRequired":true,"uniqueKey":"progress.completion","typeLabel":"number"}},"isRequired":true,"uniqueKey":"progress","typeLabel":"object"},"createdAt":{"type":"string","description":"Created timestamp","example":"2026-08-20T09:00:00Z","isRequired":true,"uniqueKey":"createdAt","typeLabel":"string"},"updatedAt":{"type":"string","description":"Updated timestamp","example":"2026-08-20T11:42:00Z","isRequired":true,"uniqueKey":"updatedAt","typeLabel":"string"},"scheduledAt":{"oneOf":[{"type":"string","format":"date-time","description":"When a scheduled run will start dialling, or `null` for one that launches immediately. Set together with the `SCHEDULED` status.","example":"2026-09-15T09:00:00Z","uniqueKey":"scheduledAt.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","format":"date-time","description":"When a scheduled run will start dialling, or `null` for one that launches immediately. Set together with the `SCHEDULED` status.","example":"2026-09-15T09:00:00Z","uniqueKey":"scheduledAt.oneOf.1","typeLabel":"null"}],"uniqueKey":"scheduledAt","typeLabel":"string\u003cdate-time> | null"},"scheduleError":{"oneOf":[{"type":"string","description":"Why a scheduled run did not start at its time, or `null`. A scheduled launch is re-admitted against billing when it fires, and a refusal then has no request to answer - it is reported here instead. The run stays `SCHEDULED` and is retried, so resolving the cause is enough to make it go.","example":"Insufficient minutes available to schedule 10 interviews (50 minutes total). Please purchase additional minutes.","uniqueKey":"scheduleError.oneOf.0","typeLabel":"string"},{"type":"null","description":"Why a scheduled run did not start at its time, or `null`. A scheduled launch is re-admitted against billing when it fires, and a refusal then has no request to answer - it is reported here instead. The run stays `SCHEDULED` and is retried, so resolving the cause is enough to make it go.","example":"Insufficient minutes available to schedule 10 interviews (50 minutes total). Please purchase additional minutes.","uniqueKey":"scheduleError.oneOf.1","typeLabel":"null"}],"uniqueKey":"scheduleError","typeLabel":"string | null"}},"required":["id","name","agentId","status","progress","createdAt","updatedAt"],"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"id":"789e0123-e45b-67d8-a901-234567890123","name":"Q3 product follow-ups","agentId":"456e7890-e12b-34d5-a678-901234567890","status":"RUNNING","progress":{"total":42,"queued":30,"inProgress":3,"completed":8,"failed":1,"cancelled":0,"unreachable":0,"completion":0.21},"createdAt":"2026-08-20T09:00:00Z","updatedAt":"2026-08-20T11:42:00Z","scheduledAt":"2026-09-15T09:00:00Z","scheduleError":"Insufficient minutes available to schedule 10 interviews (50 minutes total). Please purchase additional minutes."}}},"exampleType":"generated"}},"exampleType":"generated"},"fbbbae8f-613d-484c-9b78-9df7935432c4":{"description":"Unprocessable Entity - the agent is not a custom agent, or does not belong to this company.","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":400,"isRequired":true,"uniqueKey":"statusCode","typeLabel":"integer"},"message":{"type":"string","example":"Validation failed","isRequired":true,"uniqueKey":"message","typeLabel":"string"},"error":{"type":"string","example":"Bad Request","uniqueKey":"error","typeLabel":"string"}},"required":["statusCode","message"],"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"statusCode":400,"message":"Validation failed","error":"Bad Request"}}},"exampleType":"generated"}},"exampleType":"generated"}},"security":{"ec16b59f-6a3a-49b1-adc2-be794652fb7a":{"bearer":{"type":"http","scheme":"bearer","description":"API key for authentication using Bearer scheme","scopes":[],"schemeName":"bearer"}}},"servers":{"fefe9da2-a252-4644-8424-0eaff357a7a8":{"url":"https://api.instaview.sk","description":"Production API Gateway"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"http","scheme":"bearer","description":"API key for authentication using Bearer scheme","scopes":[],"schemeName":"bearer"},"schema":{"title":"Bearer Auth","type":"string","isRequired":true,"description":"API key for authentication using Bearer scheme","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"bearer","name":"Authorization"}],"title":"bearer"}]},"originalFileLocation":"api-reference/openapi.json"},"subdomain":"instaview","siteName":"InstaView API","title":"Create Run - InstaView API","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-08-29T18:01:34.260Z","originalFileLocation":"api-reference/runs/create-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=\"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=\"Creates an empty draft run for a custom agent. A draft dials nothing: attach contacts, then launch. Contacts are deliberately not accepted here - a retried create would otherwise leave a second draft holding the same list, and that draft is exactly the thing someone launches later \u0026#x27;to be safe\u0026#x27;.\">\u003cmeta data-mint-head name=\"application-name\" content=\"InstaView API\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/instaview/FzS1-dDCztzdlzmX/_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/instaview/FzS1-dDCztzdlzmX/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/instaview/FzS1-dDCztzdlzmX/_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/instaview/FzS1-dDCztzdlzmX/_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/instaview/FzS1-dDCztzdlzmX/_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/instaview/FzS1-dDCztzdlzmX/_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/instaview/FzS1-dDCztzdlzmX/_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/instaview/FzS1-dDCztzdlzmX/_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/instaview/FzS1-dDCztzdlzmX/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Create Run - InstaView API\">\u003cmeta data-mint-head property=\"og:description\" content=\"Creates an empty draft run for a custom agent. A draft dials nothing: attach contacts, then launch. Contacts are deliberately not accepted here - a retried create would otherwise leave a second draft holding the same list, and that draft is exactly the thing someone launches later \u0026#x27;to be safe\u0026#x27;.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"InstaView API\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.instaview.sk/api-reference/runs/create-run\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://instaview.mintlify.app/_mintlify/api/og/v2?division=Runs\u0026amp;title=Create+Run\u0026amp;description=Creates+an+empty+draft+run+for+a+custom+agent.+A+draft+dials+nothing%3A+attach+contacts%2C+then+launch.+Contacts+are+deliberately+not+accepted+here+-+a+retried+crea\u0026amp;theme=1444b1b95306a409923bc3c0\u0026amp;signature=018cc417d6c71e37d3733a6d395711c3d6575fceaae57f3d9421d3882b3f4573\">\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=\"Create Run - InstaView API\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Creates an empty draft run for a custom agent. A draft dials nothing: attach contacts, then launch. Contacts are deliberately not accepted here - a retried create would otherwise leave a second draft holding the same list, and that draft is exactly the thing someone launches later \u0026#x27;to be safe\u0026#x27;.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://instaview.mintlify.app/_mintlify/api/og/v2?division=Runs\u0026amp;title=Create+Run\u0026amp;description=Creates+an+empty+draft+run+for+a+custom+agent.+A+draft+dials+nothing%3A+attach+contacts%2C+then+launch.+Contacts+are+deliberately+not+accepted+here+-+a+retried+crea\u0026amp;theme=1444b1b95306a409923bc3c0\u0026amp;signature=018cc417d6c71e37d3733a6d395711c3d6575fceaae57f3d9421d3882b3f4573\">\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/instaview/FzS1-dDCztzdlzmX/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"InstaView API\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#2741F9\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.instaview.sk/api-reference/runs/create-run\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/runs/create-run.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.instaview.sk/#organization\",\"name\":\"InstaView API\",\"url\":\"https://docs.instaview.sk\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/instaview/srYC_WLR3UAwt0PY/logo/light.svg?fit=max\u0026auto=format\u0026n=srYC_WLR3UAwt0PY\u0026q=85\u0026s=a941bc948e20b3503a55e49b4438bfd8\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.instaview.sk#website\",\"name\":\"InstaView API\",\"url\":\"https://docs.instaview.sk\",\"publisher\":{\"@id\":\"https://docs.instaview.sk/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.instaview.sk/api-reference/runs/create-run#webpage\",\"url\":\"https://docs.instaview.sk/api-reference/runs/create-run\",\"name\":\"Create Run\",\"description\":\"Creates an empty draft run for a custom agent. A draft dials nothing: attach contacts, then launch. Contacts are deliberately not accepted here - a retried create would otherwise leave a second draft holding the same list, and that draft is exactly the thing someone launches later 'to be safe'.\",\"dateModified\":\"2026-08-29T18:01:34.260Z\",\"isPartOf\":{\"@id\":\"https://docs.instaview.sk#website\"},\"breadcrumb\":{\"@id\":\"https://docs.instaview.sk/api-reference/runs/create-run#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.instaview.sk/api-reference/runs/create-run#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"InstaView API\",\"item\":\"https://docs.instaview.sk\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Create Run\",\"item\":\"https://docs.instaview.sk/api-reference/runs/create-run\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.instaview.sk/api-reference/runs/create-run#apireference\",\"headline\":\"Create Run\",\"name\":\"Create Run\",\"description\":\"Creates an empty draft run for a custom agent. A draft dials nothing: attach contacts, then launch. Contacts are deliberately not accepted here - a retried create would otherwise leave a second draft holding the same list, and that draft is exactly the thing someone launches later 'to be safe'.\",\"url\":\"https://docs.instaview.sk/api-reference/runs/create-run\",\"mainEntityOfPage\":{\"@id\":\"https://docs.instaview.sk/api-reference/runs/create-run#webpage\"},\"dateModified\":\"2026-08-29T18:01:34.260Z\",\"publisher\":{\"@id\":\"https://docs.instaview.sk/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.instaview.sk#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"InstaView API\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"InstaView API","nav":{"global":null,"tabs":[{"tab":"Documentation","icon":"book","pages":[{"title":"Documentation","href":"/introduction"}]},{"tab":"API Reference","icon":"code","groups":[{"group":"Overview","pages":[{"title":"API Reference","href":"/api-reference/introduction"}]},{"group":"Agents","pages":[{"title":"List Agents","openapi":"GET /agents","href":"/api-reference/agents/list-agents"},{"title":"Design an Agent","openapi":"POST /agents/composer","href":"/api-reference/agents/compose-agent"},{"title":"Refine a Composed Agent","openapi":"POST /agents/composer/{sessionId}/messages","href":"/api-reference/agents/refine-agent"},{"title":"Poll a Composer Session","openapi":"GET /agents/composer/{sessionId}","href":"/api-reference/agents/get-composer-session"},{"title":"Create Agent","openapi":"POST /agents","href":"/api-reference/agents/create-agent"},{"title":"Get Agent","openapi":"GET /agents/{id}","href":"/api-reference/agents/get-agent"},{"title":"Update Agent","openapi":"PATCH /agents/{id}","href":"/api-reference/agents/update-agent"},{"title":"Delete Agent","openapi":"DELETE /agents/{id}","href":"/api-reference/agents/delete-agent"}]},{"group":"Agent Knowledge Base","pages":[{"title":"List Knowledge Documents","openapi":"GET /agents/{id}/knowledge","href":"/api-reference/agents/knowledge/list-knowledge"},{"title":"Start Knowledge Upload","openapi":"POST /agents/{id}/knowledge","href":"/api-reference/agents/knowledge/start-upload"},{"title":"Complete Knowledge Upload","openapi":"POST /agents/{id}/knowledge/{documentId}/complete","href":"/api-reference/agents/knowledge/complete-upload"},{"title":"Update Knowledge Document","openapi":"PATCH /agents/{id}/knowledge/{documentId}","href":"/api-reference/agents/knowledge/update-knowledge"},{"title":"Delete Knowledge Document","openapi":"DELETE /agents/{id}/knowledge/{documentId}","href":"/api-reference/agents/knowledge/delete-knowledge"}]},{"group":"Jobs","pages":[{"title":"List Jobs","openapi":"GET /jobs","href":"/api-reference/jobs/list-jobs"},{"title":"Create Job","openapi":"POST /jobs","href":"/api-reference/jobs/create-job"},{"title":"Create Job from URL","openapi":"POST /jobs/url","href":"/api-reference/jobs/create-job-from-url"},{"title":"Get Job","openapi":"GET /jobs/{id}","href":"/api-reference/jobs/get-job"},{"title":"Update Job","openapi":"PATCH /jobs/{id}","href":"/api-reference/jobs/update-job"},{"title":"Delete Job","openapi":"DELETE /jobs/{id}","href":"/api-reference/jobs/delete-job"}]},{"group":"Contacts","pages":[{"title":"List Contacts","openapi":"GET /contacts","href":"/api-reference/contacts/list-contacts"},{"title":"Create Contact","openapi":"POST /contacts","href":"/api-reference/contacts/create-contact"},{"title":"Get Contact","openapi":"GET /contacts/{id}","href":"/api-reference/contacts/get-contact"},{"title":"Update Contact","openapi":"PATCH /contacts/{id}","href":"/api-reference/contacts/update-contact"},{"title":"Delete Contact","openapi":"DELETE /contacts/{id}","href":"/api-reference/contacts/delete-contact"}]},{"group":"Contact Documents","pages":[{"title":"List Contact Documents","openapi":"GET /contacts/{id}/documents","href":"/api-reference/contacts/documents/list-documents"},{"title":"Start Contact Document Upload","openapi":"POST /contacts/{id}/documents/uploads","href":"/api-reference/contacts/documents/start-upload"},{"title":"Complete Contact Document Upload","openapi":"POST /contacts/{id}/documents/{documentId}/complete","href":"/api-reference/contacts/documents/complete-upload"},{"title":"Update Contact Document","openapi":"PATCH /contacts/{id}/documents/{documentId}","href":"/api-reference/contacts/documents/update-document"},{"title":"Delete Contact Document","openapi":"DELETE /contacts/{id}/documents/{documentId}","href":"/api-reference/contacts/documents/delete-document"}]},{"group":"Contact Fields","pages":[{"title":"List Contact Fields","openapi":"GET /contact-fields","href":"/api-reference/contact-fields/list-contact-fields"},{"title":"Create Contact Field","openapi":"POST /contact-fields","href":"/api-reference/contact-fields/create-contact-field"},{"title":"Update Contact Field","openapi":"PATCH /contact-fields/{id}","href":"/api-reference/contact-fields/update-contact-field"},{"title":"Delete Contact Field","openapi":"DELETE /contact-fields/{id}","href":"/api-reference/contact-fields/delete-contact-field"}]},{"group":"Companies","pages":[{"title":"List Companies","openapi":"GET /company","href":"/api-reference/companies/list-companies"},{"title":"Create Company","openapi":"POST /company","href":"/api-reference/companies/create-company"},{"title":"Get Company","openapi":"GET /company/{id}","href":"/api-reference/companies/get-company"},{"title":"Update Company","openapi":"PATCH /company/{id}","href":"/api-reference/companies/update-company"},{"title":"Delete Company","openapi":"DELETE /company/{id}","href":"/api-reference/companies/delete-company"}]},{"group":"Conversations","pages":[{"title":"List Conversations","openapi":"GET /conversations","href":"/api-reference/conversations/list-conversations"},{"title":"Create Conversation","openapi":"POST /conversations","href":"/api-reference/conversations/create-conversation"},{"title":"Get Conversation","openapi":"GET /conversations/{id}","href":"/api-reference/conversations/get-conversation"},{"title":"Get Conversation Analysis PDF","openapi":"GET /conversations/{id}/analysis-pdf","href":"/api-reference/conversations/get-conversation-analysis-pdf"},{"title":"Invoke New Call Attempt","openapi":"POST /conversations/{id}/call-attempts","href":"/api-reference/conversations/invoke-call-attempt"},{"title":"Reschedule Call Attempt","openapi":"PATCH /conversations/{id}/call-attempts/{attemptId}","href":"/api-reference/conversations/reschedule-call-attempt"},{"title":"Delete Call Attempt","openapi":"DELETE /conversations/{id}/call-attempts/{attemptId}","href":"/api-reference/conversations/delete-call-attempt"},{"title":"Delete Conversation","openapi":"DELETE /conversations/{id}","description":"Permanently deletes a conversation and all associated data (transcripts, recordings, and analyses). This action is irreversible. A scheduled conversation is removed from the processing queue. For one already in progress, the active call continues to its natural end, but all post-call processing is skipped and concurrency slots are released.","href":"/api-reference/conversations/delete-conversation"}]},{"group":"Runs","pages":[{"title":"Create Run","openapi":"POST /runs","href":"/api-reference/runs/create-run"},{"title":"Get Run","openapi":"GET /runs/{id}","description":"Returns one run with its lifecycle status and aggregate progress, ensuring it belongs to the API key's company. A run batches conversations rather than replacing them: it mints one conversation per contact, and `progress` counts those. For the per-contact detail behind the aggregate, use `GET /runs/{id}/conversations`.","href":"/api-reference/runs/get-run"},{"title":"List Run Conversations","openapi":"GET /runs/{id}/conversations","href":"/api-reference/runs/list-run-conversations"},{"title":"Attach Contacts","openapi":"POST /runs/{id}/contacts","href":"/api-reference/runs/attach-run-contacts"},{"title":"Detach Contact","openapi":"DELETE /runs/{id}/contacts/{contactId}","href":"/api-reference/runs/detach-run-contact"},{"title":"Launch Run","openapi":"POST /runs/{id}/launch","href":"/api-reference/runs/launch-run"},{"title":"Pause Run","openapi":"POST /runs/{id}/pause","href":"/api-reference/runs/pause-run"},{"title":"Resume Run","openapi":"POST /runs/{id}/resume","href":"/api-reference/runs/resume-run"},{"title":"Cancel Run","openapi":"POST /runs/{id}/cancel","href":"/api-reference/runs/cancel-run"},{"title":"Delete Run","openapi":"DELETE /runs/{id}","href":"/api-reference/runs/delete-run"}]},{"group":"Billing","pages":[{"title":"Get Usage Statistics","openapi":"GET /billing/usage","href":"/api-reference/billing/get-usage"}]},{"group":"Voice","pages":[{"title":"Generate Audio","openapi":"POST /voice","href":"/api-reference/voice/generate-audio"}]},{"group":"Webhooks","pages":[{"title":"List Webhooks","api":"GET /webhooks","href":"/api-reference/webhooks/list-webhooks"},{"title":"Create Webhook","api":"POST /webhooks","href":"/api-reference/webhooks/create-webhook"},{"title":"Get Webhook","api":"GET /webhooks/{id}","href":"/api-reference/webhooks/get-webhook"},{"title":"Update Webhook","api":"PATCH /webhooks/{id}","href":"/api-reference/webhooks/update-webhook"},{"title":"Delete Webhook","api":"DELETE /webhooks/{id}","href":"/api-reference/webhooks/delete-webhook"},{"title":"Test Webhook","api":"POST /webhooks/{id}/test","href":"/api-reference/webhooks/test-webhook"},{"title":"Reset Circuit Breaker","api":"POST /webhooks/{id}/reset-circuit","href":"/api-reference/webhooks/reset-circuit"}]},{"group":"Sourcing","pages":[{"title":"Initiate Sourcing Run","openapi":"POST /sourcing","href":"/api-reference/sourcing/initiate-sourcing"},{"title":"Initiate Sourcing Preview Run","openapi":"POST /sourcing/preview","href":"/api-reference/sourcing/initiate-sourcing-preview"},{"title":"Get Sourcing Preview Results","openapi":"GET /sourcing/preview/{id}/results","href":"/api-reference/sourcing/get-sourcing-preview-results"},{"title":"Patch Sourcing Run","openapi":"PATCH /sourcing/{id}","href":"/api-reference/sourcing/patch-sourcing"},{"title":"Get Sourcing Results","openapi":"GET /sourcing/{id}/results","href":"/api-reference/sourcing/get-sourcing-results"},{"title":"Initiate Enrichment Run","openapi":"POST /sourcing/enrich","href":"/api-reference/sourcing/initiate-enrichment"},{"title":"Get Enrichment Results","openapi":"GET /sourcing/enrich/{id}/results","href":"/api-reference/sourcing/get-enrich-results"},{"title":"Render HTML Candidate Cards","openapi":"POST /sourcing/render-html","href":"/api-reference/sourcing/render-html"}]},{"group":"Phone Numbers","pages":[{"title":"List Phone Numbers","openapi":"GET /phone-numbers","href":"/api-reference/phone-numbers/list-phone-numbers"}]}]},{"tab":"Changelog","icon":"clock","pages":[{"title":"Changelog","href":"/changelog/introduction"}]}]},"title":"Create Run - InstaView API","buildId":"dpl_849ArpqvBiCczQiT1Y1stNGpbqHT","deploymentId":"dpl_849ArpqvBiCczQiT1Y1stNGpbqHT","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-Bbp7I60D.js","utils-C3RIvJha.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-DqD-vLt8.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-B31Loprg.js","snippetPresets-DKpk-b8t.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","ApiExamples-Cj65AhOR.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-BXtn5gcC.js","shallow-RY2b03Cp.js","getApiPlaygroundDisplay-B0jeiPk3.js","CodeSnippet-CYgBjjwn.js","CodeSnippets-DOngDrYB.js","Page-n7I5XbKb.js","getPastedJson-DRQbJx-T.js","icon-CQiQCicY.js","MethodPill-BKTLdNtu.js","DuplicateIcon-B9jpAdat.js","createIcon-DCddRrXv.js","DynamicMarkdown-a8hUKrw6.js","SectionHeading-eECVV2eH.js","axios-vUo_bRtp.js","Markdown--GF7ZIpf.js","clsx-DZLdJUrt.js","lib--scc4DXi.js","lib-B8HbPgcC.js","html-void-elements-mCSPHezU.js","dist-2LoAhjKH.js","katex-YMM-FMeD.js","marked.esm-CZWythHk.js","AssistantPageLink-Zwc0ZncM.js"]}