Skip to main content
POST
/
api
/
v2
/
agents
/
sequence
/
run
Sequence Agent
curl --request POST \
  --url https://app.octavehq.com/api/v2/agents/sequence/run \
  --header 'Content-Type: application/json' \
  --header 'api_key: <api-key>' \
  --data '
{
  "email": "john.doe@example.com",
  "firstName": "<string>",
  "lastName": "<string>",
  "jobTitle": "<string>",
  "companyDomain": "example.com",
  "companyName": "<string>",
  "linkedInProfile": "<string>",
  "crmContactId": "<string>",
  "crmLeadId": "<string>",
  "crmAccountId": "<string>",
  "lang": "<string>",
  "requestId": "<string>",
  "outputFormat": "text",
  "runtimeContext": {
    "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": {
    "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": "<string>",
  "customContext": {},
  "fullSequenceMode": true,
  "agentOId": "agent_123",
  "experimentOId": "experiment_123",
  "includeFullAnnotation": true
}
'
{
  "_metadata": {
    "requestId": "requestId",
    "timestamp": "2021-01-01T00:00:00.000Z",
    "usage": 0,
    "message": "message"
  },
  "found": true,
  "message": "Additional information",
  "data": {
    "emails": [
      {
        "email": "<string>",
        "subject": "<string>",
        "coreValueProp": "",
        "sections": {
          "greeting": "",
          "opening": "",
          "body": "",
          "closing": "",
          "cta": "",
          "ps": "",
          "signature": ""
        },
        "metadata": {
          "openerPattern": "<string>",
          "hookTopic": "<string>",
          "ctaVerb": "<string>",
          "valuePropsUsed": [
            "<string>"
          ],
          "referencesUsed": [
            "<string>"
          ]
        }
      }
    ],
    "product": {
      "oId": "<string>",
      "name": "<string>",
      "description": "<string>",
      "matchAnalysis": "<string>"
    },
    "service": {
      "oId": "<string>",
      "name": "<string>",
      "description": "<string>",
      "matchAnalysis": "<string>"
    },
    "solution": {
      "oId": "<string>",
      "name": "<string>",
      "description": "<string>",
      "matchAnalysis": "<string>"
    },
    "playbook": {
      "oId": "<string>",
      "name": "<string>",
      "description": "<string>",
      "matchAnalysis": "<string>"
    },
    "persona": {
      "oId": "<string>",
      "name": "<string>",
      "description": "<string>",
      "matchAnalysis": "<string>"
    },
    "useCases": [
      {
        "oId": "<string>",
        "name": "<string>",
        "description": "<string>",
        "matchAnalysis": "<string>"
      }
    ],
    "referenceCustomers": [
      {
        "oId": "<string>",
        "name": "<string>",
        "description": "<string>",
        "matchAnalysis": "<string>"
      }
    ],
    "annotations": {
      "annotations": [
        {
          "type": "<string>",
          "title": "<string>",
          "meta": null,
          "description": "<string>",
          "url": "<string>"
        }
      ],
      "metadata": null
    }
  }
}

​
Runtime Context & Instructions

The API uses runtimeContext and runtimeInstructions to pass dynamic per-contact data to your agent at execution time. These are not the same fields as the MCP tool schema (which uses allEmailsContext / allEmailsInstructions).
If you’re migrating from the MCP tool to the direct API, note the schema difference:
MCP Tool FieldAPI Field
allEmailsContextruntimeContext.all
allEmailsInstructionsruntimeInstructions.all
step1ContextruntimeContext.1
step1InstructionsruntimeInstructions.1

​
How keys work

Both runtimeContext and runtimeInstructions accept an object where keys control which email steps receive the content:
KeyScope
"all"Applied to every email in the sequence
"1"Applied to step 1 only
"2"Applied to step 2 only
"3"Applied to step 3 only
"4"Applied to step 4 only
Step-specific values are merged with "all" — they don’t replace it. Use "all" when you have one block of context for the whole sequence (which is the most common case).

​
Context vs Instructions

  • runtimeContext — Factual information the agent should draw from: account research, LinkedIn data, recent activity, deal context. Think of this as “what the agent knows about this person.”
  • runtimeInstructions — Behavioral directives that steer how the agent writes: tone, length, what to emphasize, what to avoid. Think of this as “how the agent should write.”

​
Example: Event follow-up with rich context

{
  "agentOId": "ca_JxNickJCXUdxFQe2CFKCF",
  "outputFormat": "text",
  "firstName": "Sarah",
  "lastName": "Jackson",
  "companyName": "NICE Ltd",
  "companyDomain": "nice.com",
  "jobTitle": "Strategic Alliance Director",
  "email": "sarah.jackson@nice.com",
  "linkedInProfile": "https://www.linkedin.com/in/sarah-jackson-nice",
  "runtimeContext": {
    "all": "ACCOUNT RESEARCH:\nNICE Ltd expanded their AI partner program from 25 to 200 partners in 18 months. Sarah led the AWS SCA partnership and drove the partner enablement strategy.\n\nEVENT ATTENDANCE:\nAttended Partner Signal Live on 2025-03-15. Participated in the 'Scaling Partner-Led Growth' breakout session.\n\nLINKEDIN CONTEXT:\n12 years in strategic alliances. Previously at Genesys building channel programs. Posts frequently about partner ecosystem strategy."
  },
  "runtimeInstructions": {
    "all": "Keep emails under 150 words. Reference specific details from the event and her LinkedIn background. Use a peer-to-peer tone — she's a senior alliances leader, not a prospect to be pitched.",
    "1": "Lead with a specific detail from the event breakout session she attended. Do not use a generic 'thanks for attending' opener."
  }
}

​
Example: Simple context (all steps)

If you only need one block of context for the whole sequence, use the "all" key: 
{
  "agentOId": "YOUR_AGENT_OID",
  "firstName": "Alex",
  "lastName": "Chen",
  "companyName": "Datadog",
  "jobTitle": "VP Engineering",
  "email": "alex.chen@datadoghq.com",
  "outputFormat": "text",
  "runtimeContext": {
    "all": "Datadog recently announced a new AI observability product. Alex's team is responsible for the core monitoring platform and has been hiring for ML engineers."
  }
}

Authorizations

​
api_key
string
header
required

Body

application/json

Generate emails input

​
email
string | null

Email of the person to generate emails for

Example:

"john.doe@example.com"

​
firstName
string | null

First name of the person to generate emails for

​
lastName
string | null
​
jobTitle
string | null

Job title of the person to generate emails for

​
companyDomain
string | null

Company domain of the person to generate emails for

Example:

"example.com"

​
companyName
string | null

Company name of the person to generate emails for

​
linkedInProfile
string | null

LinkedIn profile of the person to generate emails for

​
crmContactId
string | null
​
crmLeadId
string | null
​
crmAccountId
string | null
​
lang
string | null

Language of the person to generate emails for

​
requestId
string | null
​
outputFormat
enum<string> | null
default:text

Output format of the emails to generate

Available options:
text,
html,
markdown
​
runtimeContext
object

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
object

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
string | null

Playbook selection context of the person to generate emails for

​
customContext
object
​
fullSequenceMode
boolean
​
agentOId
string

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
string

ExperimentOId is required when running an experiment

Example:

"experiment_123"

​
includeFullAnnotation
boolean

If true, returns full annotation data including metadata. If false or omitted (default), returns minimal annotations to reduce response size.

Response

Generate emails successful

​
_metadata
object
required
​
found
boolean
required

Whether the operation was successful

Example:

true

​
message
string | null

Message

Example:

"Additional information"

​
data
object