Sequence Lifecycle

The Sequences page covers basic operations (list, get, run, pause/resume, manage enrolled contacts). This page covers the lifecycle endpoints used to author and inspect a sequence end-to-end - typically what a CLI or build tool needs.

All endpoints share the /sequences prefix and require a Bearer API key.

A sequence in a transitional status (scheduling, pausing, resuming, terminating) cannot be PATCHed - you’ll get 409 Conflict. Wait for the operation to settle.

For machine-readable schemas see the interactive API docs.

Enum reference

• step_type (case-insensitive): EMAIL | PHONE | SMS | WHATSAPP | HEYREACH | MANUAL_DIALER. The alias linkedin maps to HEYREACH. For Unipile-based LinkedIn pass UNIPILE explicitly.
• input_type: ON_DEMAND | MANUAL_TEMPLATE | AI_GENERATED_TEMPLATE. Aliases: template / manual → MANUAL_TEMPLATE; ai / ai_template → AI_GENERATED_TEMPLATE.
• channel_type: SMTP | GMAIL | INBOXKIT | PHONE | LINKEDIN | SMS | WHATSAPP.

step_data by channel

step_data is a free-form object whose meaningful keys depend on step_type. Unknown keys are silently ignored — a key that belongs to another channel has no effect. Pick the keys for your step’s channel from the sections below.

EMAIL

{
  "subject": "...",
  "body": "...",
  "instructions": "...",
  "email_type": "plain"
}

HEYREACH / LinkedIn

step_type: "HEYREACH" (or the linkedin alias). linkedin_action_type is required — a LinkedIn step without it is accepted at create time but fails at send time.

{
  "linkedin_action_type": "MESSAGE",
  "linkedin_message_text": "Hi {{first_name}}, ..."
}

For AI-generated LinkedIn copy: set input_type: "AI_GENERATED_TEMPLATE" on the step, plus step_data.linkedin_input_mode: "instructions" and step_data.linkedin_instructions: "<prompt>". Use linkedin_input_mode: "manual" with the explicit copy keys above for fixed text.

PHONE / MANUAL_DIALER

{
  "dial_dnc": false,
  "phone_options": ["mobile", "direct"]
}

SMS / WHATSAPP

{
  "message_body": "...",
  "media_urls": ["https://..."],
  "whatsapp_template_sid": "...",
  "whatsapp_template_variables": {}
}

Create Sequence

POST /sequences

Create a sequence in drafted status. You can optionally include steps[] and channels[] in the same call.

Request Body

Step config

Channel config

Example

curl -X POST "https://be.graph8.com/api/v1/sequences" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q2 Outbound",
    "user_email": "[email protected]",
    "associated_list_id": 5,
    "steps": [
      {
        "step_order": 1,
        "step_type": "EMAIL",
        "input_type": "MANUAL_TEMPLATE",
        "time_interval": 0,
        "step_data": {"subject": "Quick intro", "body": "Hi {{first_name}}..."}
      }
    ],
    "channels": [
      {
        "channel_id": 12,
        "channel_value": "[email protected]",
        "channel_type": "SMTP"
      }
    ]
  }'

Response 201 Created

{
  "data": {
    "id": "seq_abc",
    "name": "Q2 Outbound",
    "status": "drafted",
    "created_at": "2026-04-15T10:00:00Z"
  }
}

Errors

Preview Sequence

GET /sequences/{sequence_id}/preview

Read-only view of a sequence with all steps and channels. Does not enroll anyone.

Path Parameters

Example

curl "https://be.graph8.com/api/v1/sequences/seq_abc/preview" \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "data": {
    "id": "seq_abc",
    "name": "Q2 Outbound",
    "status": "drafted",
    "description": null,
    "steps": [
      {
        "id": "stp_1",
        "step_order": 1,
        "step_type": "EMAIL",
        "input_type": "MANUAL_TEMPLATE",
        "time_interval": 0,
        "step_data": {"subject": "Quick intro", "body": "..."}
      }
    ],
    "channels": [
      {"id": "ch_1", "channel_id": 12, "channel_value": "[email protected]", "channel_type": "SMTP"}
    ]
  }
}

Update Sequence

PATCH /sequences/{sequence_id}

Update sequence metadata. Send only the fields you want to change. Returns 409 if the sequence is in a transitional status (scheduling, pausing, resuming, terminating).

Path Parameters

Request Body

All fields are optional.

Example

curl -X PATCH "https://be.graph8.com/api/v1/sequences/seq_abc" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Q2 Outbound v2", "send_in_same_thread": true}'

Errors

Update Step

PATCH /sequences/{sequence_id}/steps/{step_id}

Update a single step. The same 409 rule applies if the parent sequence is transitioning.

Path Parameters

Request Body

All fields are optional.

Example

curl -X PATCH "https://be.graph8.com/api/v1/sequences/seq_abc/steps/stp_1" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"step_data": {"subject": "Quick intro v2", "body": "Updated..."}}'

Pause / Resume

POST /sequences/{sequence_id}/pause POST /sequences/{sequence_id}/resume

Pause a live sequence (or resume a paused one). Returns the number of contacts affected.

Response

{
  "data": {
    "sequence_id": "seq_abc",
    "status": "paused",
    "contacts_affected": 150
  }
}

Analytics

GET /sequences/{sequence_id}/analytics

Returns a comprehensive analytics report - overview KPIs, performance over time, engagement breakdown, contact distribution, per-step metrics, and sender distribution. The shape mirrors the internal SequenceReports model.

Example

curl "https://be.graph8.com/api/v1/sequences/seq_abc/analytics" \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "data": {
    "overview": {"sent": 320, "opened": 180, "replied": 22},
    "performance": {"open_rate": 0.56, "reply_rate": 0.07},
    "engagement": {"by_day": [...]},
    "timeline": [...],
    "contact_distribution": {"active": 150, "completed": 100, "stopped": 70},
    "step_breakdown": [
      {"step_id": "stp_1", "sent": 320, "opened": 180}
    ],
    "step_creation_methods": [...],
    "sender_distribution": [...]
  }
}

The full schema lives at /api/v1/docs under SequenceAnalyticsResponse.

Delete (Archive)

DELETE /sequences/{sequence_id}

Soft-deletes a sequence by setting is_archived = true. Already-archived sequences return 400. Sequences in certain non-terminal states cannot be archived and return 409.

Example

curl -X DELETE "https://be.graph8.com/api/v1/sequences/seq_abc" \
  -H "Authorization: Bearer $API_KEY"

Errors