Sequences API — Control Live Outreach Sequence Runs

A sequence is a live outreach run created for a single contact when they are enrolled in a sequence template. It executes each configured step — emails, LinkedIn messages, manual tasks — according to the template’s schedule, and tracks the contact’s current position and state. The Sequences API lets you monitor and control those runs programmatically: filter by status, pause runs during a sales blackout, or stop them cleanly when a deal is won or lost.

All Sequences endpoints require a valid API key. Read-only endpoints require the sequences:read scope; write operations (update, pause, resume, stop) require sequences:write.

The sequence object

string (UUID)

required

Unique identifier for the sequence run.

organization_id

string (UUID)

required

The workspace this sequence belongs to.

contact_id

string (UUID) | null

required

The contact this sequence is targeting. May be null if the contact record has been deleted.

sequence_template_id

string (UUID)

required

The template the sequence was instantiated from.

status

string

required

Current execution state. See Sequence statuses below.

variables

object | null

Per-run template variable overrides merged on top of the template defaults. Keys and values are both strings; a null value removes a variable override. Example: {"first_name": "Amélie", "company": "Acme Corp"}.

source_contact_list_id

string (UUID) | null

The contact list that triggered this sequence, if any.

last_step_executed_at

string (ISO 8601) | null

Timestamp of when the most recently executed step ran.

created_at

string (ISO 8601)

required

When the sequence was created.

updated_at

string (ISO 8601)

required

When the sequence was last modified.

Sequence statuses

Status	Description
`ACTIVE`	The sequence is running and steps will execute on schedule.
`WAITING_FOR_LEAD`	Execution is paused and will resume automatically at a future time (e.g., honoring a `paused_until` value set via the pause endpoint).
`WAITING_FOR_USER`	A manual step is pending — the sequence is blocked until a user completes or skips the task.
`SUCCEEDED`	All steps completed successfully; the sequence has finished.
`FAILED`	The sequence ended due to an internal error or unrecoverable delivery failure.
`STOPPED_EARLY`	The sequence was deliberately terminated via the stop endpoint.
`COMPLETED`	The sequence finished all available steps (terminal, same family as `SUCCEEDED`).
`FOUND`	An intermediate state during lead processing before the sequence is fully activated.
`REFUSED`	The contact was rejected at enrollment time and the sequence never started.

The terminal states are SUCCEEDED, COMPLETED, FAILED, and STOPPED_EARLY. Sequences in these states cannot be resumed.

List sequences

Requires scope: sequences:read

Returns a paginated list of sequence runs in your workspace. Apply filters to narrow results by status, contact, or template.

GET /v1/sequences

Query parameters

status

string

Filter by execution state. One of: ACTIVE, WAITING_FOR_LEAD, WAITING_FOR_USER, SUCCEEDED, FAILED, STOPPED_EARLY, COMPLETED, FOUND, REFUSED.

sequence_template_id

string (UUID)

Return only sequences that were created from this template.

created_at_after

string (ISO 8601)

Return sequences created strictly after this timestamp.

created_at_before

string (ISO 8601)

Return sequences created strictly before this timestamp.

sort_by

string

Field to sort results by. One of: created_at, updated_at, status. Defaults to created_at.

sort_order

string

Sort direction. asc or desc. Defaults to asc.

page

integer

Page number (1-indexed). Defaults to 1.

size

integer

Number of items per page. Between 1 and 100. Defaults to 10.

Response

items

array

Array of sequence objects on this page.

total_count

integer

Total number of sequences matching the query across all pages.

total_pages

integer

Total number of pages at the current size.

has_more

boolean

true if additional pages exist after the current one.

Example — list active sequences

curl "https://api.topo.io/v1/sequences?status=ACTIVE&sort_by=created_at&sort_order=desc&size=20" \
  -H "Authorization: Bearer topo_xxxxxxxxxxxx"

{
  "items": [
    {
      "id": "018f3c1a-4b2d-7e8f-9a0b-1c2d3e4f5a6b",
      "organization_id": "018e9d8c-7b6a-7f5e-4d3c-2b1a0f9e8d7c",
      "contact_id": "019a1b2c-3d4e-7f80-9182-a3b4c5d6e7f8",
      "sequence_template_id": "018d7e6f-5c4b-7a39-8281-c0d1e2f3a4b5",
      "status": "ACTIVE",
      "variables": {
        "intro_line": "I noticed your team recently expanded into EMEA"
      },
      "source_contact_list_id": "019b2c3d-4e5f-7081-9283-b4c5d6e7f809",
      "last_step_executed_at": "2025-03-12T08:14:22Z",
      "created_at": "2025-03-10T09:00:00Z",
      "updated_at": "2025-03-12T08:14:22Z"
    }
  ],
  "total_count": 142,
  "total_pages": 8,
  "has_more": true
}

Get a sequence

Requires scope: sequences:read

Fetches a single sequence run by its ID.

GET /v1/sequences/{id}

Path parameters

string (UUID)

required

The ID of the sequence to retrieve.

Example

curl "https://api.topo.io/v1/sequences/018f3c1a-4b2d-7e8f-9a0b-1c2d3e4f5a6b" \
  -H "Authorization: Bearer topo_xxxxxxxxxxxx"

Update a sequence

Requires scope: sequences:write

Partially updates a sequence run. Currently supports updating the variables dictionary — per-run template variable overrides that are substituted into outbound message content.

PATCH /v1/sequences/{id}

Path parameters

string (UUID)

required

The ID of the sequence to update.

Request body

variables

object

A dictionary of string key/value pairs to merge into the sequence’s runtime variables. Set a key’s value to null to remove that override and fall back to the template default.

Example

curl -X PATCH "https://api.topo.io/v1/sequences/018f3c1a-4b2d-7e8f-9a0b-1c2d3e4f5a6b" \
  -H "Authorization: Bearer topo_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "intro_line": "Congrats on the Series B — exciting milestone!"
    }
  }'

Pause a sequence

Requires scope: sequences:write

Pauses an active sequence until a specified datetime. The sequence transitions to WAITING_FOR_LEAD and will automatically resume after paused_until. Use this to hold off outreach during a scheduled sales call, a public holiday, or any other blackout window.

POST /v1/sequences/{id}/pause

Path parameters

string (UUID)

required

The ID of the sequence to pause.

Request body

paused_until

string (ISO 8601)

required

The datetime at which the sequence should automatically resume. Must be in the future.

Example — pause until after the weekend

curl -X POST "https://api.topo.io/v1/sequences/018f3c1a-4b2d-7e8f-9a0b-1c2d3e4f5a6b/pause" \
  -H "Authorization: Bearer topo_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "paused_until": "2025-03-17T09:00:00Z"
  }'

Resume a sequence

Requires scope: sequences:write

Resumes a sequence that is currently paused (WAITING_FOR_LEAD). The sequence transitions back to ACTIVE and will continue executing steps on schedule.

POST /v1/sequences/{id}/resume

Path parameters

string (UUID)

required

The ID of the sequence to resume.

Example

curl -X POST "https://api.topo.io/v1/sequences/018f3c1a-4b2d-7e8f-9a0b-1c2d3e4f5a6b/resume" \
  -H "Authorization: Bearer topo_xxxxxxxxxxxx"

This endpoint returns a 422 error if the sequence is not currently in a paused state. Terminal sequences (SUCCEEDED, COMPLETED, FAILED, STOPPED_EARLY) cannot be resumed.

Stop a sequence

Requires scope: sequences:write

Permanently stops a sequence. This is irreversible — a stopped sequence cannot be restarted. The reason field signals the commercial outcome and the scope field controls whether to stop just this contact’s sequence or all active sequences in the same template that target the same company.

POST /v1/sequences/{id}/stop

Path parameters

string (UUID)

required

The ID of the sequence to stop.

Request body

reason

string

required

Why the sequence is being stopped. One of:

WIN — the deal was won; no further outreach needed.
LOSE — the deal was lost or the contact is not a fit.

scope

string

required

Controls the blast radius of the stop operation. One of:

CONTACT — stop only this specific sequence run.
COMPANY — stop this sequence and all other active sequences in the same template that target contacts at the same company.

Example — mark a win and suppress the whole account

curl -X POST "https://api.topo.io/v1/sequences/018f3c1a-4b2d-7e8f-9a0b-1c2d3e4f5a6b/stop" \
  -H "Authorization: Bearer topo_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "WIN",
    "scope": "COMPANY"
  }'

{
  "id": "018f3c1a-4b2d-7e8f-9a0b-1c2d3e4f5a6b",
  "organization_id": "018e9d8c-7b6a-7f5e-4d3c-2b1a0f9e8d7c",
  "contact_id": "019a1b2c-3d4e-7f80-9182-a3b4c5d6e7f8",
  "sequence_template_id": "018d7e6f-5c4b-7a39-8281-c0d1e2f3a4b5",
  "status": "STOPPED_EARLY",
  "variables": null,
  "source_contact_list_id": null,
  "last_step_executed_at": "2025-03-12T08:14:22Z",
  "created_at": "2025-03-10T09:00:00Z",
  "updated_at": "2025-03-12T11:05:47Z"
}

Stopping a sequence is permanent. There is no undo. If you need to re-engage a contact, you must enroll them in a new sequence from the Topo UI.

​The sequence object

​Sequence statuses

​List sequences

​Query parameters

​Response

​Example — list active sequences

​Get a sequence

​Path parameters

​Example

​Update a sequence

​Path parameters

​Request body

​Example

​Pause a sequence

​Path parameters

​Request body

​Example — pause until after the weekend

​Resume a sequence

​Path parameters

​Example

​Stop a sequence

​Path parameters

​Request body

​Example — mark a win and suppress the whole account

The sequence object

Sequence statuses

List sequences

Query parameters

Response

Example — list active sequences

Get a sequence

Path parameters

Example

Update a sequence

Path parameters

Request body

Example

Pause a sequence

Path parameters

Request body

Example — pause until after the weekend

Resume a sequence

Path parameters

Example

Stop a sequence

Path parameters

Request body

Example — mark a win and suppress the whole account