> ## Documentation Index > Fetch the complete documentation index at: https://docs.octavehq.com/llms.txt > Use this file to discover all available pages before exploring further. # Run Agents > Asynchronously run agents by providing the relevant input payload and a `callbackUrl`. Once processing is complete, the result will be sent to your provided callback URL. ## Important Notes - This is an **asynchronous** endpoint. - You must include a `callbackUrl` where the result will be posted after the agent completes execution. - You need to specify an `agentOId`. - Based on the `agentOId`, the input schema must match the structure expected by the selected agent. The following agents are supported. Each has its own required input format. Click below to view the specific documentation and input schema: - [Enrich Company Agent](/v2-api-reference/agents/enrich-company-agent) - [Enrich Person Agent](/v2-api-reference/agents/enrich-person-agent) - [Content Agent](/v2-api-reference/agents/content-agent) - [Sequence Agent](/v2-api-reference/agents/sequence-agent) - [Prospector Agent](/v2-api-reference/agents/prospector-agent) - [Qualify Person Agent](/v2-api-reference/agents/qualify-person-agent) - [Qualify Company Agent](/v2-api-reference/agents/qualify-company-agent) - [Call Prep Agent](/v2-api-reference/agents/call-prep-agent) ## OpenAPI ````yaml post /api/v2/async/agent/run openapi: 3.0.0 info: version: 1.0.0 title: Octave API description: API for Octave workspace management and AI-powered content generation servers: - url: https://app.octavehq.com security: - ApiKeyAuth: [] paths: /api/v2/async/agent/run: post: tags: - Async summary: Run Agent description: Asynchronously run agents operationId: asyncRunAgent parameters: - schema: type: string description: >- Optional header used to identify the source of the request. Helps us apply appropriate rate limiting or disable it when necessary. example: some-source required: false description: >- Optional header used to identify the source of the request. Helps us apply appropriate rate limiting or disable it when necessary. name: x-request-source in: header - schema: type: string description: >- External Request ID. Add this header to identify the request from the client for better tracking and debugging. example: external-request-id required: false description: >- External Request ID. Add this header to identify the request from the client for better tracking and debugging. name: x-external-request-id in: header requestBody: content: application/json: schema: anyOf: - type: object properties: companyDomain: type: string nullable: true description: Company domain to enrich example: example.com companyName: type: string nullable: true description: Company name to enrich example: Example crmAccountId: type: string nullable: true runtimeContext: nullable: true description: Runtime context example: user: oId: user_123 agentOId: type: string description: Agent OId example: ca_... includeFullAnnotation: type: boolean description: >- If true, returns full annotation data including metadata. If false or omitted (default), returns minimal annotations to reduce response size. callbackUrl: type: string format: uri description: >- Optional callback URL. If provided, results are POSTed to this URL on completion. If omitted, poll GET /async/agent/run/status with the returned requestId instead. example: https://example.com/api/callbacks/unique-id experimentOId: type: string description: Experiment OId example: ae_... title: Enrich Company - type: object properties: email: type: string nullable: true description: Email of the person to enrich example: john.doe@example.com firstName: type: string nullable: true description: First name of the person to enrich example: John lastName: type: string nullable: true jobTitle: type: string nullable: true description: Job title of the person to enrich example: Software Engineer companyDomain: type: string nullable: true description: Company domain of the person to enrich companyName: type: string nullable: true description: Company name of the person to enrich example: Example linkedInProfile: type: string nullable: true description: LinkedIn profile of the person to enrich example: https://www.linkedin.com/in/john-doe/ crmContactId: type: string nullable: true crmLeadId: type: string nullable: true crmAccountId: type: string nullable: true runtimeContext: nullable: true description: Runtime context example: user: oId: user_123 agentOId: type: string description: Agent OId example: ca_... includeFullAnnotation: type: boolean description: >- If true, returns full annotation data including metadata. If false or omitted (default), returns minimal annotations to reduce response size. callbackUrl: type: string format: uri description: >- Optional callback URL. If provided, results are POSTed to this URL on completion. If omitted, poll GET /async/agent/run/status with the returned requestId instead. example: https://example.com/api/callbacks/unique-id experimentOId: type: string description: Experiment OId example: ae_... title: Enrich Person - type: object properties: email: type: string nullable: true description: Email of the person to generate content for example: john.doe@example.com firstName: type: string nullable: true description: First name of the person to generate content for lastName: type: string nullable: true jobTitle: type: string nullable: true description: Job title of the person to generate content for companyDomain: type: string nullable: true description: Company domain to generate content for example: example.com companyName: type: string nullable: true description: Company name to generate content for linkedInProfile: type: string nullable: true description: LinkedIn profile of the person to generate content for crmContactId: type: string nullable: true crmLeadId: type: string nullable: true crmAccountId: type: string nullable: true runtimeContext: nullable: true description: Runtime context url: type: string nullable: true description: URL to generate content for customContext: type: object nullable: true properties: playbook: type: object properties: oId: type: string required: - oId product: type: object properties: oId: type: string required: - oId service: type: object properties: oId: type: string required: - oId persona: type: object properties: oId: type: string required: - oId segment: type: object properties: oId: type: string required: - oId description: >- Pins specific library entities for this run, overriding the agent's configured selection. Each field takes the oId of an entity in your workspace, and that exact entity is used with no re-matching. On motion agents, playbook.oId must be an active motion playbook; if the agent is configured with a specific motion, the playbook must belong to that motion or the request fails with a 400. product/service pin the offering unless the resolved motion playbook supplies its own (reported as a run warning). example: persona: oId: pe_xxxxxxxxxxxxxxxxxxxxx segment: oId: sg_xxxxxxxxxxxxxxxxxxxxx outputFormat: type: string nullable: true enum: - JSON - TEXT - HTML - MARKDOWN - null agentOId: type: string description: Agent OId example: ca_... experimentOId: type: string description: Experiment OId example: ae_... includeFullAnnotation: type: boolean description: >- If true, returns full annotation data including metadata. If false or omitted (default), returns minimal annotations to reduce response size. callbackUrl: type: string format: uri description: >- Optional callback URL. If provided, results are POSTed to this URL on completion. If omitted, poll GET /async/agent/run/status with the returned requestId instead. example: https://example.com/api/callbacks/unique-id title: Content Agent required: - agentOId - type: object properties: email: type: string nullable: true description: Email of the person to generate emails for example: john.doe@example.com firstName: type: string nullable: true description: First name of the person to generate emails for lastName: type: string nullable: true jobTitle: type: string nullable: true description: Job title of the person to generate emails for companyDomain: type: string nullable: true description: Company domain of the person to generate emails for example: example.com companyName: type: string nullable: true description: Company name of the person to generate emails for linkedInProfile: type: string nullable: true description: LinkedIn profile of the person to generate emails for crmContactId: type: string nullable: true crmLeadId: type: string nullable: true crmAccountId: type: string nullable: true lang: type: string nullable: true description: Language of the person to generate emails for requestId: type: string nullable: true outputFormat: type: string nullable: true enum: - text - html - markdown - null default: text description: Output format of the emails to generate runtimeContext: type: object additionalProperties: type: string description: >- Additional context (facts, research, account data) injected at runtime to personalize the generated sequence. Keys control which email steps receive the context: "all" applies to every email, "1"-"4" apply to a specific step (1-based index). Step-specific context is merged with the "all" context. example: '1': Reference her AWS SCA leadership role in the opening. all: >- Account research: NICE Ltd expanded their AI partner program from 25 to 200 partners. Sarah leads strategic alliances. runtimeInstructions: type: object additionalProperties: type: string description: >- Behavioral directives that control how the agent writes the sequence — tone, structure, emphasis, constraints. Keys work the same way as runtimeContext: "all" applies to every email, "1"-"4" apply to a specific step (1-based index). Use runtimeInstructions for writing style directives. Use runtimeContext for factual data. example: '1': >- Lead with a specific personal detail — do not open with a generic intro. all: >- Keep emails under 150 words. Use a consultative tone, not salesy. playbookSelectionContext: type: string nullable: true description: >- Playbook selection context of the person to generate emails for customContext: type: object nullable: true properties: playbook: type: object properties: oId: type: string required: - oId product: type: object properties: oId: type: string required: - oId service: type: object properties: oId: type: string required: - oId persona: type: object properties: oId: type: string required: - oId segment: type: object properties: oId: type: string required: - oId description: >- Pins specific library entities for this run, overriding the agent's configured selection. Each field takes the oId of an entity in your workspace, and that exact entity is used with no re-matching. On motion agents, playbook.oId must be an active motion playbook; if the agent is configured with a specific motion, the playbook must belong to that motion or the request fails with a 400. product/service pin the offering unless the resolved motion playbook supplies its own (reported as a run warning). example: persona: oId: pe_xxxxxxxxxxxxxxxxxxxxx segment: oId: sg_xxxxxxxxxxxxxxxxxxxxx fullSequenceMode: type: boolean agentOId: type: string description: Agent OId example: ca_... experimentOId: type: string description: Experiment OId example: ae_... includeFullAnnotation: type: boolean description: >- If true, returns full annotation data including metadata. If false or omitted (default), returns minimal annotations to reduce response size. callbackUrl: type: string format: uri description: >- Optional callback URL. If provided, results are POSTed to this URL on completion. If omitted, poll GET /async/agent/run/status with the returned requestId instead. example: https://example.com/api/callbacks/unique-id title: Sequence Agent required: - agentOId - type: object properties: email: type: string nullable: true description: Email of the person to qualify example: john.doe@example.com firstName: type: string nullable: true description: First name of the person to qualify lastName: type: string nullable: true jobTitle: type: string nullable: true description: Job title of the person to qualify companyDomain: type: string nullable: true description: Company domain of the person to qualify example: example.com companyName: type: string nullable: true description: Company name of the person to qualify linkedInProfile: type: string nullable: true description: LinkedIn profile of the person to qualify crmContactId: type: string nullable: true crmLeadId: type: string nullable: true crmAccountId: type: string nullable: true runtimeContext: nullable: true description: Runtime context for qualification agentOId: type: string description: Agent OId example: ca_... includeFullAnnotation: type: boolean description: >- If true, returns full annotation data including metadata. If false or omitted (default), returns minimal annotations to reduce response size. callbackUrl: type: string format: uri description: >- Optional callback URL. If provided, results are POSTed to this URL on completion. If omitted, poll GET /async/agent/run/status with the returned requestId instead. example: https://example.com/api/callbacks/unique-id experimentOId: type: string description: Experiment OId example: ae_... title: Qualify Person Agent required: - agentOId - type: object properties: companyDomain: type: string description: Company to find prospects or use as lookalike source example: example.com limit: type: number nullable: true description: Override the Agent's configured limit example: 10 minimum: 1 maximum: 1000 minimal: type: boolean default: true description: >- Minimize the output. If set to true, `positions`, `internalPictureUrl`, and the nested `company` object will be omitted from the output. example: true searchContext: type: object properties: playbookOId: type: string nullable: true personaOIds: type: array nullable: true items: type: string fuzzyTitles: type: array nullable: true items: type: string exactTitles: type: array nullable: true items: type: string excludeTitles: type: array nullable: true items: type: string personCountry: type: object nullable: true properties: matches: type: object properties: exact: type: array items: type: string contains: type: array items: type: string prefix: type: array items: type: string excludes: type: object properties: exact: type: array items: type: string contains: type: array items: type: string prefix: type: array items: type: string personLocation: type: object nullable: true properties: countryCode: type: object properties: matches: type: object properties: exact: type: array items: type: string contains: type: array items: type: string prefix: type: array items: type: string excludes: type: object properties: exact: type: array items: type: string contains: type: array items: type: string prefix: type: array items: type: string city: type: object properties: matches: type: object properties: exact: type: array items: type: string contains: type: array items: type: string prefix: type: array items: type: string excludes: type: object properties: exact: type: array items: type: string contains: type: array items: type: string prefix: type: array items: type: string text: type: object properties: matches: type: object properties: exact: type: array items: type: string contains: type: array items: type: string prefix: type: array items: type: string excludes: type: object properties: exact: type: array items: type: string contains: type: array items: type: string prefix: type: array items: type: string description: >- Optional search context to override agent's configured search context. If provided, the two objects will be merged. agentOId: type: string description: Agent OId example: ca_... callbackUrl: type: string format: uri description: >- Optional callback URL. If provided, results are POSTed to this URL on completion. If omitted, poll GET /async/agent/run/status with the returned requestId instead. example: https://example.com/api/callbacks/unique-id experimentOId: type: string description: Experiment OId example: ae_... required: - agentOId title: Prospector Agent - type: object properties: companyDomain: type: string nullable: true description: Company domain to qualify example: example.com companyName: type: string nullable: true description: Company name to qualify crmAccountId: type: string nullable: true runtimeContext: nullable: true description: Runtime context for qualification agentOId: type: string description: Agent OId example: ca_... includeFullAnnotation: type: boolean description: >- If true, returns full annotation data including metadata. If false or omitted (default), returns minimal annotations to reduce response size. callbackUrl: type: string format: uri description: >- Optional callback URL. If provided, results are POSTed to this URL on completion. If omitted, poll GET /async/agent/run/status with the returned requestId instead. example: https://example.com/api/callbacks/unique-id experimentOId: type: string description: Experiment OId example: ae_... title: Qualify Company Agent required: - agentOId description: Run agent by given input, the input is different for each agent oneOf: - $ref: '#/components/schemas/EnrichCompanyAgentInput' title: Enrich Company - $ref: '#/components/schemas/EnrichPersonAgentInput' title: Enrich Person - $ref: '#/components/schemas/GenerateContentAgentInput' title: Content Agent - $ref: '#/components/schemas/SequenceAgentInput' title: Sequence Agent - $ref: '#/components/schemas/QualifyPersonAgentInput' title: Qualify Person Agent - $ref: '#/components/schemas/QualifyCompanyAgentInput' title: Qualify Company Agent responses: '200': description: Agent data content: application/json: schema: type: object properties: status: type: string enum: - pending - completed - failed description: Status example: pending message: type: string nullable: true description: Message example: Additional information requestId: type: string example: requestId description: Request ID agentOId: type: string description: The Agent OId that was selected/used for the run example: ca_... required: - status - requestId '400': description: Bad request content: application/json: schema: type: object properties: status: type: string enum: - pending - completed - failed description: Status example: pending message: type: string nullable: true description: Message example: Additional information requestId: type: string example: requestId description: Request ID required: - status - requestId example: status: failed message: Invalid callback URL requestId: 123e4567-e89b-12d3-a456-426614174000 '404': description: Agent or other resource not found content: application/json: schema: type: object properties: status: type: string enum: - pending - completed - failed description: Status example: pending message: type: string nullable: true description: Message example: Additional information requestId: type: string example: requestId description: Request ID required: - status - requestId example: status: failed message: Agent or other resource not found requestId: 123e4567-e89b-12d3-a456-426614174000 deprecated: false components: schemas: EnrichCompanyAgentInput: type: object properties: companyDomain: type: string nullable: true description: Company domain to enrich example: example.com companyName: type: string nullable: true description: Company name to enrich example: Example crmAccountId: type: string nullable: true runtimeContext: nullable: true description: Runtime context example: user: oId: user_123 agentOId: type: string description: >- AgentOId is required when creating an agent in the application. You can find it in the Agents section of your dashboard. example: agent_123 includeFullAnnotation: type: boolean description: >- If true, returns full annotation data including metadata. If false or omitted (default), returns minimal annotations to reduce response size. required: - agentOId EnrichPersonAgentInput: type: object properties: email: type: string nullable: true description: Email of the person to enrich example: john.doe@example.com firstName: type: string nullable: true description: First name of the person to enrich example: John lastName: type: string nullable: true jobTitle: type: string nullable: true description: Job title of the person to enrich example: Software Engineer companyDomain: type: string nullable: true description: Company domain of the person to enrich companyName: type: string nullable: true description: Company name of the person to enrich example: Example linkedInProfile: type: string nullable: true description: LinkedIn profile of the person to enrich example: https://www.linkedin.com/in/john-doe/ crmContactId: type: string nullable: true crmLeadId: type: string nullable: true crmAccountId: type: string nullable: true runtimeContext: nullable: true description: Runtime context example: user: oId: user_123 agentOId: type: string description: >- AgentOId is required when creating an agent in the application. You can find it in the Agents section of your dashboard. example: agent_123 includeFullAnnotation: type: boolean description: >- If true, returns full annotation data including metadata. If false or omitted (default), returns minimal annotations to reduce response size. required: - agentOId GenerateContentAgentInput: type: object properties: email: type: string nullable: true description: Email of the person to generate content for example: john.doe@example.com firstName: type: string nullable: true description: First name of the person to generate content for lastName: type: string nullable: true jobTitle: type: string nullable: true description: Job title of the person to generate content for companyDomain: type: string nullable: true description: Company domain to generate content for example: example.com companyName: type: string nullable: true description: Company name to generate content for linkedInProfile: type: string nullable: true description: LinkedIn profile of the person to generate content for crmContactId: type: string nullable: true crmLeadId: type: string nullable: true crmAccountId: type: string nullable: true runtimeContext: nullable: true description: Runtime context url: type: string nullable: true description: URL to generate content for customContext: type: object nullable: true properties: playbook: type: object properties: oId: type: string required: - oId product: type: object properties: oId: type: string required: - oId service: type: object properties: oId: type: string required: - oId persona: type: object properties: oId: type: string required: - oId segment: type: object properties: oId: type: string required: - oId description: >- Pins specific library entities for this run, overriding the agent's configured selection. Each field takes the oId of an entity in your workspace, and that exact entity is used with no re-matching. On motion agents, playbook.oId must be an active motion playbook; if the agent is configured with a specific motion, the playbook must belong to that motion or the request fails with a 400. product/service pin the offering unless the resolved motion playbook supplies its own (reported as a run warning). example: persona: oId: pe_xxxxxxxxxxxxxxxxxxxxx segment: oId: sg_xxxxxxxxxxxxxxxxxxxxx outputFormat: type: string nullable: true enum: - JSON - TEXT - HTML - MARKDOWN - null agentOId: type: string description: >- AgentOId is required when creating an agent in the application. You can find it in the Agents section of your dashboard. example: agent_123 experimentOId: type: string description: ExperimentOId is required when running an experiment example: experiment_123 includeFullAnnotation: type: boolean description: >- If true, returns full annotation data including metadata. If false or omitted (default), returns minimal annotations to reduce response size. SequenceAgentInput: type: object properties: email: type: string nullable: true description: Email of the person to generate emails for example: john.doe@example.com firstName: type: string nullable: true description: First name of the person to generate emails for lastName: type: string nullable: true jobTitle: type: string nullable: true description: Job title of the person to generate emails for companyDomain: type: string nullable: true description: Company domain of the person to generate emails for example: example.com companyName: type: string nullable: true description: Company name of the person to generate emails for linkedInProfile: type: string nullable: true description: LinkedIn profile of the person to generate emails for crmContactId: type: string nullable: true crmLeadId: type: string nullable: true crmAccountId: type: string nullable: true lang: type: string nullable: true description: Language of the person to generate emails for requestId: type: string nullable: true outputFormat: type: string nullable: true enum: - text - html - markdown - null default: text description: Output format of the emails to generate runtimeContext: type: object additionalProperties: type: string description: >- Additional context (facts, research, account data) injected at runtime to personalize the generated sequence. Keys control which email steps receive the context: "all" applies to every email, "1"-"4" apply to a specific step (1-based index). Step-specific context is merged with the "all" context. example: '1': Reference her AWS SCA leadership role in the opening. all: >- Account research: NICE Ltd expanded their AI partner program from 25 to 200 partners. Sarah leads strategic alliances. runtimeInstructions: type: object additionalProperties: type: string description: >- Behavioral directives that control how the agent writes the sequence — tone, structure, emphasis, constraints. Keys work the same way as runtimeContext: "all" applies to every email, "1"-"4" apply to a specific step (1-based index). Use runtimeInstructions for writing style directives. Use runtimeContext for factual data. example: '1': >- Lead with a specific personal detail — do not open with a generic intro. all: Keep emails under 150 words. Use a consultative tone, not salesy. playbookSelectionContext: type: string nullable: true description: Playbook selection context of the person to generate emails for customContext: type: object nullable: true properties: playbook: type: object properties: oId: type: string required: - oId product: type: object properties: oId: type: string required: - oId service: type: object properties: oId: type: string required: - oId persona: type: object properties: oId: type: string required: - oId segment: type: object properties: oId: type: string required: - oId description: >- Pins specific library entities for this run, overriding the agent's configured selection. Each field takes the oId of an entity in your workspace, and that exact entity is used with no re-matching. On motion agents, playbook.oId must be an active motion playbook; if the agent is configured with a specific motion, the playbook must belong to that motion or the request fails with a 400. product/service pin the offering unless the resolved motion playbook supplies its own (reported as a run warning). example: persona: oId: pe_xxxxxxxxxxxxxxxxxxxxx segment: oId: sg_xxxxxxxxxxxxxxxxxxxxx fullSequenceMode: type: boolean agentOId: type: string description: >- AgentOId is required when creating an agent in the application. You can find it in the Agents section of your dashboard. example: agent_123 experimentOId: type: string description: ExperimentOId is required when running an experiment example: experiment_123 includeFullAnnotation: type: boolean description: >- If true, returns full annotation data including metadata. If false or omitted (default), returns minimal annotations to reduce response size. QualifyPersonAgentInput: type: object properties: email: type: string nullable: true description: Email of the person to qualify example: john.doe@example.com firstName: type: string nullable: true description: First name of the person to qualify lastName: type: string nullable: true jobTitle: type: string nullable: true description: Job title of the person to qualify companyDomain: type: string nullable: true description: Company domain of the person to qualify example: example.com companyName: type: string nullable: true description: Company name of the person to qualify linkedInProfile: type: string nullable: true description: LinkedIn profile of the person to qualify crmContactId: type: string nullable: true crmLeadId: type: string nullable: true crmAccountId: type: string nullable: true runtimeContext: nullable: true description: Runtime context for qualification agentOId: type: string description: >- AgentOId is required when creating an agent in the application. You can find it in the Agents section of your dashboard. example: agent_123 includeFullAnnotation: type: boolean description: >- If true, returns full annotation data including metadata. If false or omitted (default), returns minimal annotations to reduce response size. required: - agentOId QualifyCompanyAgentInput: type: object properties: companyDomain: type: string nullable: true description: Company domain to qualify example: example.com companyName: type: string nullable: true description: Company name to qualify crmAccountId: type: string nullable: true runtimeContext: nullable: true description: Runtime context for qualification agentOId: type: string description: >- AgentOId is required when creating an agent in the application. You can find it in the Agents section of your dashboard. example: agent_123 includeFullAnnotation: type: boolean description: >- If true, returns full annotation data including metadata. If false or omitted (default), returns minimal annotations to reduce response size. required: - agentOId securitySchemes: ApiKeyAuth: type: apiKey in: header name: api_key ````