# Sequences

<!-- BEGIN GENERATED: guide-map -->
## Guide map

Read only the section needed for the next decision. Line ranges are exact
for this generated runtime target.

| Section | What it covers | Lines |
| --- | --- | --- |
| [Purpose](#purpose) | Scope, ownership, and the central operating question. | 26-38 |
| [Use This When](#use-this-when) | Tasks and conditions that belong in this guide. | 39-54 |
| [Do Not Use This For](#do-not-use-this-for) | Boundaries and the correct routes for excluded work. | 55-67 |
| [Mental Model](#mental-model) | Concepts and state boundaries needed for correct operation. | 68-87 |
| [Preflight](#preflight) | State, authority, inputs, and readiness to verify before execution. | 88-121 |
| [Risk And Side Effects](#risk-and-side-effects) | Effects, approvals, cost, privacy, and retry boundaries. | 122-141 |
| [Canonical Operating Pattern](#canonical-operating-pattern) | The normal end-to-end execution sequence. | 142-167 |
| [Core SDK Surfaces](#core-sdk-surfaces) | Exact source-backed callable contracts owned by this guide. | 168-232 |
| [Data Contracts](#data-contracts) | Required identities, fields, evidence, handles, and durable shapes. | 233-328 |
| [Examples](#examples) | Representative usage patterns and code. | 329-372 |
| [Verification](#verification) | Evidence required before reporting success. | 373-388 |
| [Troubleshooting](#troubleshooting) | Failure diagnosis and corrective routes. | 389-401 |
| [Related References](#related-references) | Adjacent boundaries and when to cross them. | 402-413 |
<!-- END GENERATED: guide-map -->

## Purpose

Use this reference for sequence lifecycle and mutation work after the sequence
shape is known: inspecting existing sequences, paging current audiences,
staging reviewed rows, checking imports, publishing, transferring, and deleting
staged lead lists. It also owns routing guidance for sequence destination sync:
provider-writing Audience sync config and runs belong with sequence state, not
with read-only CRM fetch helpers.

This is the activation and mutation guide. Draft source selection, AI-filter
shape, step topology, copy variables, copy verification, and source/AI-filter
preview design belong to `sequence_authoring.md`.

## Use This When

- Selecting or inspecting an existing sequence before a mutation.
- Paging current sequence audience rows for suppression, repair, or audit.
- Paging source-scoped audience rows before staging another batch into the same
  source node or ingress.
- Staging reviewed local CSV rows or durable artifact rows into a sequence
  source.
- Checking import/source-run status after staging.
- Publishing or activating a prepared sequence after explicit user
  confirmation.
- Reviewing or explaining sequence destination sync settings, manual sync runs,
  whole-audience sync, row status, or HubSpot/custom-object projection from a
  sequence audience.
- Transferring a sequence or deleting a staged/imported lead list.

## Do Not Use This For

| Task | Use Instead |
| --- | --- |
| Designing a draft sequence source, initial AI filter, copy steps, or copy variables. | `sequence_authoring.md` |
| Discovering people/accounts or deciding the audience universe. | `audience_discovery.md`, `crm.md`, `web.md`, `linkedin.md`, or workflow refs |
| Deterministic local row cleanup, column mapping, variable coverage, or CSV transforms before staging. | `row_operations.md` |
| Waiting for provider/artifact jobs, paging artifact rows, or exporting job outputs. | `artifacts_jobs.md` |
| Generating personalization, running sequence personalization, writing personalization notes, or updating audience enrichment variables. | `copy.md` |
| Sender/mailbox/domain setup, sender matching, sandbox delivery, or purchases. | `mailboxes.md` |
| Running or repairing a generated Workflow Play that happens to stage rows. | `workflow_operations.md`, then return here for sequence mutation boundaries |
| Debugging live Temporal/runtime delivery failures, quota behavior, or sequence worker incidents. | Repository sequence diagnostics, especially `bun run sequence:diagnose -- ...` |

## Mental Model

A sequence has separate lifecycle boundaries:

| Boundary | Meaning | Normal SDK Surface |
| --- | --- | --- |
| Draft authoring | Source entry topology, filter prompt, copy steps, and builder handoff. | `sequence_authoring.md` |
| Operational sources | Source ingress configuration, lifecycle, preview, and audience acquisition. These changes apply without publishing a draft. | `vf.sequences.list_sources(...)`, `vf.sequences.add_source(...)`, `vf.sequences.update_source_config(...)`, `vf.sequences.disconnect_source(...)` |
| Source preview | Pull sample source rows and diagnostics before staging or publishing. | `vf.sequences.run_source_preview(...)` |
| AI-filter preview | Test pass/reject/needs-data logic before saving or publishing a prompt. | `vf.sequences.run_ai_filter_preview(...)` |
| Staging/import | Attach reviewed rows to a sequence source. CSV upload stages and promotes source rows in one helper; publishing is still separate. | `vf.sequences.upload_csv_to_source(...)`, `vf.sequences.stage_artifact_to_source(...)` |
| Materialized audience | People currently attached through active ingresses. Use this for duplicate suppression and repair checks. | `vf.sequences.iter_audience_rows(...)`, `vf.sequences.iter_source_audience_rows(...)` |
| Personalization/enrichment write | Add visible variables/notes to audience leads or staged rows. This can affect sequence runtime, but `copy.md` owns the operation. | `copy.md` |
| Destination sync | Copy sequence audience rows and durable engagement facts to HubSpot, the only SDK-supported destination today. This is sequence-owned config/run behavior, not `vf.crm.*` object fetch. | `vf.sequences.destination_sync_config(...)`, `vf.sequences.update_destination_sync_config(...)`, `vf.sequences.run_destination_sync(...)`, `vf.sequences.destination_sync_jobs(...)`; use `docs/destination-sync.md` for product/backend mapping details. |
| Publish/activate | Promote a prepared draft to customer-visible sequence state. `activate_sequence=False` is the SDK default; pass true only for immediate activation. | `vf.sequences.publish(...)` |

Staging rows is not the same as publishing. Publishing with activation can make
the sequence eligible for enrollment and sending according to the configured
runtime rules. Keep those calls visible and separated in the user-facing status.

## Preflight

- Confirm workspace identity with `vf.auth.status()` or
  `vf.auth.ensure_logged_in()` before touching a customer sequence.
- If the user pasted a sequence URL, parse the `org_slug` out of it BEFORE
  calling any `vf.sequences.*` function. Platform URLs are shaped
  `https://platform.verbiflow.com/w/<org-slug>/sequences/<sequence_id>/...`
  (also `/w/<org-slug>/sequences`, `/w/<org-slug>/sequences/<sequence_id>/builder`,
  `.../audience`, `.../analytics`, `.../settings`). The segment after `/w/` is
  the `org_slug`. Resolve it to `org_id` with
  `vf.auth.list_workspaces()` (match by `org_slug`), then pass
  `org_id=<resolved>` to every `vf.sequences.*` call for that sequence.
  This avoids "Sequence not found" / "Organization selection is required"
  errors when the focused workspace differs from the sequence's home, and
  does NOT change the focused workspace as a side effect.
- When the user pastes only a bare `seq_*` id with no URL and no workspace
  context, ask which workspace it belongs to instead of sweeping every org.
- Resolve the target sequence with `vf.sequences.list(...)` using explicit
  `state`, `q`, or assignee filters; then call `vf.sequences.get(sequence_id)`.
- Preserve all handles returned by reads and mutations: `sequence_id`,
  `draft_id`, `expected_draft_version`, `source_node_id`, `ingress_id`,
  `filter_node_id`, `lead_list_id`, `source_run_id`, `import_id`,
  `builder_url`, `audience_url`, and `app_url`.
- Before staging, prove row identity coverage. Rows need an email or LinkedIn/
  profile contact identifier unless `require_contact_identifier=False` is a
  deliberate operator decision.
- Before staging into a live or recurring sequence, suppress against the full
  current audience. Do not trust a single bounded page.
- Before publishing, run source preview, AI-filter preview when present, copy
  verification after any copy change, sender readiness checks, and email sandbox
  rendering when email is involved.
- For active sequences, treat audience repair as a live mutation. Print exact
  affected source/import/contact ids and counts before writing.

## Risk And Side Effects

| Operation | Risk | Required Handling |
| --- | --- | --- |
| `list`, `get`, audience row paging, and import status reads | Read-only platform calls. | Print IDs/counts and continue. |
| Audience enrollment status/analytics/import row reads | Read-only platform calls. | Preserve cursors, counts, workflow ids, and sanitized failure/status fields. |
| Source or AI-filter preview jobs | May start backend/provider/AI work and consume credits depending on the configured source/filter. | Show sample size, job/run ids, timeout/partial status, and preview rows before saving or staging. |
| Draft topology/filter/step edits | Platform writes to behavior configuration and may require publish. | Use `sequence_authoring.md`; keep builder URL and draft version visible. |
| Operational source config/lifecycle edits | Live source-registry writes. They do not require publish, but can change future acquisition and audience membership. | Preserve source node/ingress ids, use generation-aware retries, and re-read the source registry after writing. |
| CSV/artifact staging | Platform write that changes sequence source/import state. CSV upload also promotes the staged source run. | Use explicit idempotency keys for retries, print source/import ids, then verify rows through source/audience paging. |
| Webhook row ingest | Platform write that stages rows into a source by identifier-upsert semantics. | Print `source_run_id`, `inserted`, and `ingress_id`; repeats can update rows and return `inserted: 0`. |
| Attachment upload | Object-storage write. Preview URL generation is read-only and expires. | Preserve `s3_key`, `filename`, `size_bytes`, `kind`, and preview `expires_seconds`. |
| Audience enrollment trigger | Queues the audience enrollment workflow and can make rows eligible for sends. | Verify status; handle 409 "Enrollment is already running" as an operator-visible state. |
| Audience delete/holds/release | Live audience mutation. Delete soft-deletes rows and holds active runtime instances; holds pause live sends; releases can resume sends and queue repair/enrollment catch-up. | Require exact `contact_ids` or explicit all-row scope, print affected counts, then re-read audience rows/status. |
| Exclusion or bounce-protect overrides | Force-includes selected rows and can resume live sends. | Require explicit contact ids and reason when available; verify resumed rows/runtime counts. |
| Personalization/enrichment writes | Platform write to materialized audience leads or staging rows. | Use `copy.md`; return here only to verify current sequence audience/source rows after the write. |
| Destination sync config or manual run | Provider-writing sequence operation that may create/update/link destination records and timeline activity. | Use the `vf.sequences.destination_sync_*` surfaces; confirm the exact sequence, provider, selected/all-audience scope, object mapping, and run mode. Do not use `vf.crm.*` to mutate CRM records. |
| `publish(..., activate_sequence=True)` | Customer-visible activation; can make rows eligible for enrollment/sending. | Require explicit confirmation immediately before publish or activation. The SDK default is `activate_sequence=False`; pass true only when the operator explicitly wants publish-and-activate. |
| Delete/transfer | Platform mutation that can remove staged imports or change ownership. | Print target IDs and require an explicit reason before execution. |

## Canonical Operating Pattern

1. Resolve the workspace and exact sequence. Print `sequence_id`, state,
   `builder_url`, and `audience_url`.
2. If the task is draft design or source/filter/copy setup, switch to
   `sequence_authoring.md` first.
3. For staging, inspect the reviewed rows or artifact, validate variable and
   contact-identifier coverage, and dedupe against
   `vf.sequences.iter_audience_rows(...)` or
   `vf.sequences.iter_source_audience_rows(...)`.
4. Stage rows with `upload_csv_to_source(...)` or
   `stage_artifact_to_source(...)`. Use a stable idempotency key when retries
   are possible.
5. Verify staging through `imports(...)`, `import_status(...)`,
   `source_audience_counts(...)`, and paged source/audience rows.
6. Before publish or activation, re-run the activation gate: source preview,
   AI-filter preview when present, copy verification via
   `sequence_authoring.md`, sender readiness, and sandbox render checks for
   email.
7. Ask for explicit confirmation immediately before publish, destination-sync
   runs, purchases, safety.md-owned direct sends, or personalization writes
   that affect live sequence audience state.
8. After any workflow-driven staging/publish mutation, sync the Workflow Play again
   with `vf.workflows.sync(...)` so `/plays` reflects source run ids, counts,
   outputs, and activation state.

## Core SDK Surfaces

<!-- BEGIN GENERATED: core-sdk-surfaces -->
| Function | Use When | Inputs | Output And Handles To Preserve | Side Effect | Source |
| --- | --- | --- | --- | --- | --- |
| `vf.sequences.action` | Use for one explicit sequence lifecycle action such as archive, pause, resume, activate, or unarchive after confirming the target sequence. | <strong>Required</strong>: `action` (activate \| pause \| resume \| archive \| unarchive; required): Operation mode for this adapter call.; `sequence_id` (str; required): Verbiflow sequence id.<br><strong>Optional</strong>: `org_id` (str \| None; optional; default `None`): Verbiflow organization/workspace UUID. | `dict` with sequence draft/published state, steps, sources, version, and routing metadata. | platform_write | installed SDK: `verbiflow/sequences.py:742-778` |
| `vf.sequences.advanced_events` | Use for explicit sequence draft, source staging, copy verification, personalization, publish, and transfer mutations. | <strong>Required</strong>: `sequence_id` (str; required): Sequence id to inspect.<br><strong>Optional</strong>: `action_name` (str \| None; optional; default `None`): Optional action name filter.; `cursor` (str \| None; optional; default `None`): Optional opaque cursor from a prior page.; `event_kind` (action \| signal; optional; default `None`): Optional event kind filter.; `from_time` (str \| None; optional; default `None`): Optional ISO 8601 lower-bound timestamp sent as `from`.; `limit` (int; optional; default `100`): Page size. Backend clamps to 1..500.; `org_id` (str \| None; optional; default `None`): Optional workspace override for the analytics read.; `person_id` (int \| None; optional; default `None`): Optional person id filter.; `sender_account_id` (str \| None; optional; default `None`): Optional sender account filter.; `signal_type` (str \| None; optional; default `None`): Optional signal type filter.; `to_time` (str \| None; optional; default `None`): Optional ISO 8601 upper-bound timestamp sent as `to`. | `sequence_advanced_events` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data.<br><strong>Common next calls</strong>: `vf.sequences.advanced_events` | read | installed SDK: `verbiflow/sequences.py:1916-1974` |
| `vf.sequences.advanced_failures` | Use for explicit sequence draft, source staging, copy verification, personalization, publish, and transfer mutations. | <strong>Required</strong>: `sequence_id` (str; required): Sequence id to inspect.<br><strong>Optional</strong>: `cursor` (str \| None; optional; default `None`): Optional opaque cursor from a prior page.; `failure_category` (str \| None; optional; default `None`): Optional sanitized failure category filter.; `from_time` (str \| None; optional; default `None`): Optional ISO 8601 lower-bound timestamp sent as `from`.; `limit` (int; optional; default `100`): Page size. Backend clamps to 1..500.; `org_id` (str \| None; optional; default `None`): Optional workspace override for the analytics read.; `q` (str \| None; optional; default `None`): Optional person search text.; `sender_account_id` (str \| None; optional; default `None`): Optional sender account filter.; `to_time` (str \| None; optional; default `None`): Optional ISO 8601 upper-bound timestamp sent as `to`. | `sequence_advanced_failures` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data.<br><strong>Common next calls</strong>: `vf.sequences.advanced_failures` | read | installed SDK: `verbiflow/sequences.py:1862-1914` |
| `vf.sequences.advanced_people` | Use for explicit sequence draft, source staging, copy verification, personalization, publish, and transfer mutations. | <strong>Required</strong>: `sequence_id` (str; required): Sequence id to inspect.<br><strong>Optional</strong>: `current_node_id` (str \| None; optional; default `None`): Optional current sequence node filter.; `cursor` (str \| None; optional; default `None`): Optional opaque cursor from a prior page.; `failure_category` (str \| None; optional; default `None`): Optional sanitized failure category filter.; `from_time` (str \| None; optional; default `None`): Optional ISO 8601 lower-bound timestamp sent as `from`.; `limit` (int; optional; default `100`): Page size. Backend clamps to 1..500.; `org_id` (str \| None; optional; default `None`): Optional workspace override for the analytics read.; `q` (str \| None; optional; default `None`): Optional person search text.; `sender_account_id` (str \| None; optional; default `None`): Optional sender account filter.; `status` (str \| None; optional; default `None`): Optional person status filter.; `to_time` (str \| None; optional; default `None`): Optional ISO 8601 upper-bound timestamp sent as `to`. | `sequence_advanced_people` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data.<br><strong>Common next calls</strong>: `vf.sequences.advanced_people` | read | installed SDK: `verbiflow/sequences.py:1802-1860` |
| `vf.sequences.advanced_summary` | Use for explicit sequence draft, source staging, copy verification, personalization, publish, and transfer mutations. | <strong>Required</strong>: `sequence_id` (str; required): Sequence id whose sanitized advanced analytics summary should be read.<br><strong>Optional</strong>: `from_time` (str \| None; optional; default `None`): Optional ISO 8601 lower-bound timestamp sent as the `from` query parameter.; `org_id` (str \| None; optional; default `None`): Optional workspace override for the analytics read.; `to_time` (str \| None; optional; default `None`): Optional ISO 8601 upper-bound timestamp sent as the `to` query parameter. | `sequence_advanced_summary` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data.<br><strong>Common next calls</strong>: `vf.sequences.advanced_people`, `vf.sequences.advanced_failures` | read | installed SDK: `verbiflow/sequences.py:1754-1800` |
| `vf.sequences.aggregate_metrics` | Use for explicit sequence draft, source staging, copy verification, personalization, publish, and transfer mutations. | <strong>Required</strong>: none<br><strong>Optional</strong>: `org_id` (str \| None; optional; default `None`): Optional workspace override for the aggregate metrics read. | `sequence_aggregate_metrics` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data.<br><strong>Common next calls</strong>: `vf.sequences.row_metrics` | read | installed SDK: `verbiflow/sequences.py:1561-1583` |
| `vf.sequences.analytics` | Use for explicit sequence draft, source staging, copy verification, personalization, publish, and transfer mutations. | <strong>Required</strong>: `sequence_id` (str; required): Sequence id whose lifetime analytics should be read.<br><strong>Optional</strong>: `org_id` (str \| None; optional; default `None`): Optional workspace override for the analytics read. | `sequence_analytics` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data.<br><strong>Common next calls</strong>: `vf.sequences.analytics_daily`, `vf.sequences.advanced_summary` | read | installed SDK: `verbiflow/sequences.py:1627-1657` |
| `vf.sequences.analytics_daily` | Use for explicit sequence draft, source staging, copy verification, personalization, publish, and transfer mutations. | <strong>Required</strong>: `sequence_id` (str; required): Sequence id whose daily analytics buckets should be read.<br><strong>Optional</strong>: `include_per_sender` (bool; optional; default `False`): When true, include per-sender daily buckets.; `org_id` (str \| None; optional; default `None`): Optional workspace override for the analytics read.; `timeframe` (7d \| 30d \| 90d; optional; default `'30d'`): Daily analytics window. Defaults to 30d. | `sequence_analytics_daily` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data.<br><strong>Common next calls</strong>: `vf.sequences.analytics` | read | installed SDK: `verbiflow/sequences.py:1702-1752` |
| `vf.sequences.attachment_preview_url` | Use for explicit sequence draft, source staging, copy verification, personalization, publish, and transfer mutations. | <strong>Required</strong>: `s3_key` (str; required): Stable attachment handle returned by upload_attachment.; `sequence_id` (str; required): Sequence id associated with the attachment preview request.<br><strong>Optional</strong>: `org_id` (str \| None; optional; default `None`): Optional workspace override for the preview URL read. | `sequence_attachment_preview_url` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data.<br><strong>Common next calls</strong>: `vf.sequences.upload_attachment` | read | installed SDK: `verbiflow/sequences.py:2284-2328` |
| `vf.sequences.audience_counts` | Use for a cheap count of the current sequence audience before paging rows or staging more people. | <strong>Required</strong>: `sequence_id` (str; required): Verbiflow sequence id.<br><strong>Optional</strong>: `org_id` (str \| None; optional; default `None`): Verbiflow organization/workspace UUID. | `dict` with current sequence audience display counts from active audience ingresses.<br><strong>Common next calls</strong>: `vf.sequences.audience_rows` | read | installed SDK: `verbiflow/sequences.py:1146-1169` |
| `vf.sequences.audience_enrollment_status` | Use for explicit sequence draft, source staging, copy verification, personalization, publish, and transfer mutations. | <strong>Required</strong>: `sequence_id` (str; required): Sequence id whose latest audience enrollment workflow status should be read.<br><strong>Optional</strong>: `org_id` (str \| None; optional; default `None`): Optional workspace override for the read. | `sequence_audience_enrollment_status` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data.<br><strong>Common next calls</strong>: `vf.sequences.run_audience_enrollment` | read | installed SDK: `verbiflow/sequences.py:1171-1206` |
| `vf.sequences.audience_rows` | Use for one bounded page of current sequence audience rows, including mapped attributes and source provenance. | <strong>Required</strong>: `sequence_id` (str; required): Verbiflow sequence id.<br><strong>Optional</strong>: `cursor` (str \| None; optional; default `None`): Cursor parameter for `sequences.audience_rows`.; `limit` (int; optional; default `100`): Maximum number of records, preview rows, or results to request.; `org_id` (str \| None; optional; default `None`): Verbiflow organization/workspace UUID. | `dict` page with current materialized audience rows from active sequence ingresses, including mapped cells, contact ids, source provenance, runtime issue/revision metadata, total, and next cursor.<br><strong>Common next calls</strong>: `vf.sequences.audience_counts`, `vf.sequences.source_audience_rows` | read | installed SDK: `verbiflow/sequences.py:1031-1067` |
| `vf.sequences.audience_rows_all` | Use when identity-level suppression needs all current sequence audience rows and the caller intentionally wants to materialize them in memory. | <strong>Required</strong>: `sequence_id` (str; required): Verbiflow sequence id.<br><strong>Optional</strong>: `max_rows` (int \| None; optional; default `None`): Maximum rows to upload, process, or return for this call.; `org_id` (str \| None; optional; default `None`): Verbiflow organization/workspace UUID.; `page_size` (int; optional; default `500`): Number of rows/results per page. | `dict` with materialized audience rows combined across cursor pages, plus `page_count`, `returned`, `truncated`, and continuation cursor metadata.<br><strong>Common next calls</strong>: `vf.sequences.audience_counts` | read | installed SDK: `verbiflow/sequences.py:1069-1105` |
| `vf.sequences.bulk_action` | Use for the same lifecycle action across several confirmed sequence ids; print every id before mutating. | <strong>Required</strong>: `action` (activate \| pause \| resume \| archive \| unarchive \| delete; required): Operation mode for this adapter call.; `sequence_ids` (list[str]; required): Sequence ids parameter for `sequences.bulk_action`.<br><strong>Optional</strong>: `org_id` (str \| None; optional; default `None`): Verbiflow organization/workspace UUID. | `sequence_bulk_action` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data. | platform_write | installed SDK: `verbiflow/sequences.py:780-816` |
| `vf.sequences.cancel_audience_enrollment` | Use for explicit sequence draft, source staging, copy verification, personalization, publish, and transfer mutations. | <strong>Required</strong>: `sequence_id` (str; required): Sequence id whose active audience enrollment should be cancelled.<br><strong>Optional</strong>: `org_id` (str \| None; optional; default `None`): Optional workspace override for the cancel write. | `sequence_audience_enrollment_cancel` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data.<br><strong>Common next calls</strong>: `vf.sequences.audience_enrollment_status` | platform_write | installed SDK: `verbiflow/sequences.py:1246-1279` |
| `vf.sequences.delete` | Use to delete one confirmed sequence after explicit operator confirmation. | <strong>Required</strong>: `sequence_id` (str; required): Verbiflow sequence id.<br><strong>Optional</strong>: `org_id` (str \| None; optional; default `None`): Verbiflow organization/workspace UUID. | `sequence_delete` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data. | platform_write | installed SDK: `verbiflow/sequences.py:871-893` |
| `vf.sequences.delete_audience_rows` | Use for explicit sequence draft, source staging, copy verification, personalization, publish, and transfer mutations. | <strong>Required</strong>: `sequence_id` (str; required): Sequence id whose audience rows should be soft-deleted.<br><strong>Optional</strong>: `all_rows` (bool; optional; default `False`): When true, delete all active audience rows. Mutually exclusive with contact_ids.; `contact_ids` (list[str] \| None; optional; default `None`): Explicit contact ids to delete. Mutually exclusive with all_rows=True.; `org_id` (str \| None; optional; default `None`): Optional workspace override for the destructive write. | `sequence_audience_delete` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data.<br><strong>Common next calls</strong>: `vf.sequences.audience_rows` | platform_write | installed SDK: `verbiflow/sequences.py:1281-1335` |
| `vf.sequences.delete_lead_list` | Use to remove a staged/imported lead list from a sequence when it should no longer enroll. | <strong>Required</strong>: `lead_list_id` (str; required): Sequence lead-list/import id used for import status, deletion, or transfer operations.; `sequence_id` (str; required): Verbiflow sequence id.<br><strong>Optional</strong>: `org_id` (str \| None; optional; default `None`): Verbiflow organization/workspace UUID. | `dict` with sequence draft/published state, steps, sources, version, and routing metadata. | platform_write | installed SDK: `verbiflow/sequences.py:930-957` |
| `vf.sequences.destination_sync_config` | Use to read the sequence-owned destination sync config and recent jobs before changing Audience sync behavior. | <strong>Required</strong>: `sequence_id` (str; required): Verbiflow sequence id.<br><strong>Optional</strong>: `org_id` (str \| None; optional; default `None`): Verbiflow organization/workspace UUID.; `provider` (hubspot; optional; default `'hubspot'`): Destination sync provider. Currently only hubspot is supported. | `sequence_destination_sync_config` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data. | read | installed SDK: `verbiflow/sequences_destination_sync.py:38-68` |
| `vf.sequences.destination_sync_job_row_statuses` | Use to inspect selected contact row statuses for a destination sync job. | <strong>Required</strong>: `contact_ids` (list[str]; required): Contact ids parameter for `sequences.destination_sync_job_row_statuses`.; `job_id` (str; required): Backend job id returned by a start/search/enrichment/qualification call.; `sequence_id` (str; required): Verbiflow sequence id.<br><strong>Optional</strong>: `org_id` (str \| None; optional; default `None`): Verbiflow organization/workspace UUID. | `sequence_destination_sync_row_statuses` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data. | read | installed SDK: `verbiflow/sequences_destination_sync.py:253-291` |
| `vf.sequences.destination_sync_jobs` | Use to list recent destination sync jobs for a sequence before reporting or polling run progress. | <strong>Required</strong>: `sequence_id` (str; required): Verbiflow sequence id.<br><strong>Optional</strong>: `org_id` (str \| None; optional; default `None`): Verbiflow organization/workspace UUID.; `provider` (hubspot; optional; default `'hubspot'`): Destination sync provider. Currently only hubspot is supported. | `sequence_destination_sync_jobs` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data. | read | installed SDK: `verbiflow/sequences_destination_sync.py:220-251` |
| `vf.sequences.duplicate` | Use to duplicate an existing sequence before making copy, audience, or activation changes. | <strong>Required</strong>: `sequence_id` (str; required): Verbiflow sequence id.<br><strong>Optional</strong>: `org_id` (str \| None; optional; default `None`): Verbiflow organization/workspace UUID. | `dict` with sequence draft/published state, steps, sources, version, and routing metadata. | platform_write | installed SDK: `verbiflow/sequences.py:714-740` |
| `vf.sequences.get` | Use after `sequences.list` or a mutation to inspect draft state, steps, sources, and version. | <strong>Required</strong>: `sequence_id` (str; required): Verbiflow sequence id.<br><strong>Optional</strong>: `org_id` (str \| None; optional; default `None`): Verbiflow organization/workspace UUID. | `dict` with sequence draft/published state, steps, sources, version, and routing metadata.<br><strong>Common next calls</strong>: `vf.sequences.publish` | read | installed SDK: `verbiflow/sequences.py:104-131` |
| `vf.sequences.hold_audience_rows` | Use for explicit sequence draft, source staging, copy verification, personalization, publish, and transfer mutations. | <strong>Required</strong>: `sequence_id` (str; required): Sequence id whose audience rows should be manually held.<br><strong>Optional</strong>: `all_rows` (bool; optional; default `False`): When true, pause all active audience rows. Mutually exclusive with contact_ids.; `contact_ids` (list[str] \| None; optional; default `None`): Explicit contact ids to pause. Mutually exclusive with all_rows=True.; `org_id` (str \| None; optional; default `None`): Optional workspace override for the hold write. | `sequence_audience_manual_hold` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data.<br><strong>Common next calls</strong>: `vf.sequences.release_audience_holds` | platform_write | installed SDK: `verbiflow/sequences.py:1337-1391` |
| `vf.sequences.import_rows` | Use for explicit sequence draft, source staging, copy verification, personalization, publish, and transfer mutations. | <strong>Required</strong>: `lead_list_id` (str; required): Lead-list import id whose materialized rows should be read.; `sequence_id` (str; required): Sequence id that owns the lead-list import.<br><strong>Optional</strong>: `cursor` (str \| None; optional; default `None`): Optional opaque cursor from a prior import_rows page.; `limit` (int \| None; optional; default `None`): Optional page size. Must be 1..500 when provided.; `org_id` (str \| None; optional; default `None`): Optional workspace override for the import row read.; `status` (str \| None; optional; default `None`): Optional raw audience_status filter. | `sequence_import_rows` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data.<br><strong>Common next calls</strong>: `vf.sequences.import_rows_all`, `vf.sequences.iter_import_rows` | read | installed SDK: `verbiflow/sequences.py:2330-2386` |
| `vf.sequences.import_rows_all` | Use for explicit sequence draft, source staging, copy verification, personalization, publish, and transfer mutations. | <strong>Required</strong>: `lead_list_id` (str; required): Lead-list import id to page.; `sequence_id` (str; required): Sequence id that owns the import.<br><strong>Optional</strong>: `max_rows` (int \| None; optional; default `None`): Optional maximum rows to return before truncating.; `org_id` (str \| None; optional; default `None`): Optional workspace override for the import row read.; `page_size` (int; optional; default `500`): Page size. Must be 1..500.; `status` (str \| None; optional; default `None`): Optional raw audience_status filter. | `sequence_import_rows` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data.<br><strong>Common next calls</strong>: `vf.sequences.import_rows` | read | installed SDK: `verbiflow/sequences.py:2388-2429` |
| `vf.sequences.import_status` | Use to read the status for one staged/imported lead list after sequence source staging. | <strong>Required</strong>: `lead_list_id` (str; required): Sequence lead-list/import id used for import status, deletion, or transfer operations.; `sequence_id` (str; required): Verbiflow sequence id.<br><strong>Optional</strong>: `org_id` (str \| None; optional; default `None`): Verbiflow organization/workspace UUID. | `dict` with import/lead-list status for one staged sequence source, including materialization state and counts when returned by Bridge.<br><strong>Common next calls</strong>: `vf.sequences.imports`, `vf.sequences.iter_source_audience_rows` | read | installed SDK: `verbiflow/sequences.py:2475-2505` |
| `vf.sequences.imports` | Use to list staged/imported lead-list statuses for a sequence, optionally scoped to one source node or ingress. | <strong>Required</strong>: `sequence_id` (str; required): Verbiflow sequence id.<br><strong>Optional</strong>: `concurrency` (int; optional; default `8`): Maximum number of local wait/start operations to run concurrently.; `ingress_id` (str \| None; optional; default `None`): Sequence ingress/source-instance id used when patching or staging a specific source.; `org_id` (str \| None; optional; default `None`): Verbiflow organization/workspace UUID.; `source_node_id` (str \| None; optional; default `None`): Sequence source node id to preview, stage, upload, or update. | `list`/`dict` of staged/imported lead-list statuses for a sequence, optionally scoped to a source node or ingress. Preserve lead list/source run ids.<br><strong>Common next calls</strong>: `vf.sequences.import_status`, `vf.sequences.iter_source_audience_rows` | read | installed SDK: `verbiflow/sequences.py:2507-2571` |
| `vf.sequences.ingest_webhook_rows` | Use for explicit sequence draft, source staging, copy verification, personalization, publish, and transfer mutations. | <strong>Required</strong>: `contacts` (list[JsonObject]; required): Non-empty contact objects to stage. Maximum 1000. Repeated identifiers update staged rows and may report inserted: 0.; `ingress_id` (str; required): Webhook source ingress id that receives the rows.; `sequence_id` (str; required): Sequence id that owns the webhook source ingress.<br><strong>Optional</strong>: `org_id` (str \| None; optional; default `None`): Optional workspace override used when fetching the key.; `webhook_key` (str \| None; optional; default `None`): Optional webhook key. When omitted, the SDK fetches the key first. | `sequence_webhook_ingest_result` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data.<br><strong>Common next calls</strong>: `vf.sequences.import_rows` | platform_write | installed SDK: `verbiflow/sequences.py:2142-2218` |
| `vf.sequences.iter_audience_rows` | Use as the default for 1000+ person sequence suppression; it cursor-pages current audience rows without forcing one huge response. | <strong>Required</strong>: `sequence_id` (str; required): Verbiflow sequence id.<br><strong>Optional</strong>: `max_rows` (int \| None; optional; default `None`): Maximum rows to upload, process, or return for this call.; `org_id` (str \| None; optional; default `None`): Verbiflow organization/workspace UUID.; `page_size` (int; optional; default `500`): Number of rows/results per page. | `Iterator[dict]` or async iterator yielding materialized audience rows one at a time across bounded cursor pages.<br><strong>Common next calls</strong>: `vf.sequences.audience_rows_all` | read | installed SDK: `verbiflow/sequences.py:1107-1144` |
| `vf.sequences.iter_import_rows` | Use for explicit sequence draft, source staging, copy verification, personalization, publish, and transfer mutations. | <strong>Required</strong>: `lead_list_id` (str; required): Lead-list import id to stream.; `sequence_id` (str; required): Sequence id that owns the import.<br><strong>Optional</strong>: `max_rows` (int \| None; optional; default `None`): Optional maximum rows to yield before stopping.; `org_id` (str \| None; optional; default `None`): Optional workspace override for the import row read.; `page_size` (int; optional; default `500`): Page size. Must be 1..500.; `status` (str \| None; optional; default `None`): Optional raw audience_status filter. | `sequence_import_row_stream` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data.<br><strong>Common next calls</strong>: `vf.sequences.import_rows_all` | read | installed SDK: `verbiflow/sequences.py:2431-2473` |
| `vf.sequences.iter_source_audience_rows` | Use as the default for 1000+ person source-scoped suppression before staging another batch. | <strong>Required</strong>: `ingress_id` (str; required): Sequence ingress/source-instance id used when patching or staging a specific source.; `sequence_id` (str; required): Verbiflow sequence id.; `source_node_id` (str; required): Sequence source node id to preview, stage, upload, or update.<br><strong>Optional</strong>: `max_rows` (int \| None; optional; default `None`): Maximum rows to upload, process, or return for this call.; `org_id` (str \| None; optional; default `None`): Verbiflow organization/workspace UUID.; `page_size` (int; optional; default `500`): Number of rows/results per page. | `Iterator[dict]` or async iterator yielding source-scoped materialized audience rows one at a time across bounded cursor pages.<br><strong>Common next calls</strong>: `vf.sequences.source_audience_rows_all` | read | installed SDK: `verbiflow/sequences.py:2659-2700` |
| `vf.sequences.list` | Use to discover sequences in the active workspace before selecting one to inspect or mutate; pass `state='active'`, `state='ready'`, `state='draft'`, `state='paused'`, or `state='archived'` when status matters. | <strong>Required</strong>: none<br><strong>Optional</strong>: `assigned_to_user_ids` (list[str] \| None; optional; default `None`): Sequence assignee user ids used to filter sequence list results.; `limit` (int \| None; optional; default `None`): Maximum number of records, preview rows, or results to request.; `org_id` (str \| None; optional; default `None`): Verbiflow organization/workspace UUID.; `q` (str \| None; optional; default `None`): Search query or free-text filter for the operation.; `state` (SequenceListState \| list[SequenceListState]; optional; default `'all'`): Sequence display state filter: all, active, paused, ready, draft, or archived. | `dict` with `sequences` and `members`. Every `sequences` row uses the canonical fields `sequence_id`, `sequence_name`, `operational_state`, `is_archived`, `has_published_revision`, `assignments_version`, `source_registry_version`, `assigned_to`, `validation_error_count`, `created_at`, and `updated_at`. `assigned_to` and top-level `members` contain member rows with `id`, `name`, `email`, and optional `avatar_url`. Preserve these field names; do not guess aliases.<br><strong>Common next calls</strong>: `vf.sequences.get` | read | installed SDK: `verbiflow/sequences.py:37-102` |
| `vf.sequences.override_bounce_protect` | Use for explicit sequence draft, source staging, copy verification, personalization, publish, and transfer mutations. | <strong>Required</strong>: `contact_ids` (list[str]; required): Non-empty contact ids to force-include.; `sequence_id` (str; required): Sequence id whose bounce-protected audience rows should be force-included.<br><strong>Optional</strong>: `org_id` (str \| None; optional; default `None`): Optional workspace override for the override write.; `reason` (str \| None; optional; default `None`): Optional operator reason stored with the override. | `sequence_bounce_protect_override` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data.<br><strong>Common next calls</strong>: `vf.sequences.release_audience_holds` | platform_write | installed SDK: `verbiflow/sequences.py:1505-1559` |
| `vf.sequences.override_exclusions` | Use for explicit sequence draft, source staging, copy verification, personalization, publish, and transfer mutations. | <strong>Required</strong>: `contact_ids` (list[str]; required): Non-empty contact ids to force-include.; `sequence_id` (str; required): Sequence id whose global-exclusion audience rows should be force-included.<br><strong>Optional</strong>: `org_id` (str \| None; optional; default `None`): Optional workspace override for the override write.; `reason` (str \| None; optional; default `None`): Optional operator reason stored with the override. | `sequence_exclusion_override` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data.<br><strong>Common next calls</strong>: `vf.sequences.release_audience_holds` | platform_write | installed SDK: `verbiflow/sequences.py:1449-1503` |
| `vf.sequences.publish` | Use only after draft/source/copy checks pass and the sequence should become customer-visible. | <strong>Required</strong>: `sequence_id` (str; required): Verbiflow sequence id.<br><strong>Optional</strong>: `activate_sequence` (bool; optional; default `False`): Whether publish should also activate the sequence for enrollment/sending.; `auto_adopt_compatible_revisions` (bool \| None; optional; default `None`): Auto adopt compatible revisions parameter for `sequences.publish`.; `draft_id` (str \| None; optional; default `None`): Sequence draft id used for optimistic source/step updates when already known.; `expected_draft_version` (int \| None; optional; default `None`): Optimistic concurrency version for sequence draft updates.; `org_id` (str \| None; optional; default `None`): Verbiflow organization/workspace UUID. | `dict` with sequence draft/published state, steps, sources, version, and routing metadata.<br><strong>Common next calls</strong>: `vf.sequences.get` | platform_write | installed SDK: `verbiflow/sequences.py:959-1010` |
| `vf.sequences.publish_diff` | Use for explicit sequence draft, source staging, copy verification, personalization, publish, and transfer mutations. | <strong>Required</strong>: `sequence_id` (str; required): Sequence id whose unpublished draft changes should be read.<br><strong>Optional</strong>: `org_id` (str \| None; optional; default `None`): Optional workspace override for the diff read. | `sequence_publish_diff` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data.<br><strong>Common next calls</strong>: `vf.sequences.publish`, `vf.sequences.revision_diff` | read | installed SDK: `verbiflow/sequences.py:2061-2096` |
| `vf.sequences.quick_create` | Use to create a product-template-backed sequence skeleton from a supported channel kind before detailed authoring. | <strong>Required</strong>: `channel_kind` (email_only \| linkedin_only \| email_linkedin_csv; required): Allowed values: email_only, linkedin_only, email_linkedin_csv.; `sequence_name` (str; required): Sequence name parameter for `sequences.quick_create`.<br><strong>Optional</strong>: `description` (str \| None; optional; default `None`): Human-readable description for the created resource.; `org_id` (str \| None; optional; default `None`): Verbiflow organization/workspace UUID. | `dict` with sequence draft/published state, steps, sources, version, and routing metadata. | platform_write | installed SDK: `verbiflow/sequences.py:667-712` |
| `vf.sequences.release_audience_holds` | Use for explicit sequence draft, source staging, copy verification, personalization, publish, and transfer mutations. | <strong>Required</strong>: `sequence_id` (str; required): Sequence id whose manual audience holds should be released.<br><strong>Optional</strong>: `all_rows` (bool; optional; default `False`): When true, release all manual audience holds. Mutually exclusive with contact_ids.; `contact_ids` (list[str] \| None; optional; default `None`): Explicit contact ids to resume. Mutually exclusive with all_rows=True.; `org_id` (str \| None; optional; default `None`): Optional workspace override for the release write. | `sequence_audience_manual_hold_release` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data.<br><strong>Common next calls</strong>: `vf.sequences.audience_rows` | platform_write | installed SDK: `verbiflow/sequences.py:1393-1447` |
| `vf.sequences.revision_diff` | Use for explicit sequence draft, source staging, copy verification, personalization, publish, and transfer mutations. | <strong>Required</strong>: `from_revision_id` (str; required): Earlier sequence revision id.; `sequence_id` (str; required): Sequence id whose revisions should be compared.; `to_revision_id` (str; required): Later sequence revision id.<br><strong>Optional</strong>: `org_id` (str \| None; optional; default `None`): Optional workspace override for the diff read. | `sequence_revision_diff` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data.<br><strong>Common next calls</strong>: `vf.sequences.analytics` | read | installed SDK: `verbiflow/sequences.py:2013-2059` |
| `vf.sequences.revisions` | Use for explicit sequence draft, source staging, copy verification, personalization, publish, and transfer mutations. | <strong>Required</strong>: `sequence_id` (str; required): Sequence id whose published version history should be listed.<br><strong>Optional</strong>: `org_id` (str \| None; optional; default `None`): Optional workspace override for the revision list read. | `sequence_revision_list` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data.<br><strong>Common next calls</strong>: `vf.sequences.revision_diff`, `vf.sequences.publish_diff` | read | installed SDK: `verbiflow/sequences.py:1976-2011` |
| `vf.sequences.row_metrics` | Use for explicit sequence draft, source staging, copy verification, personalization, publish, and transfer mutations. | <strong>Required</strong>: `sequence_ids` (list[str]; required): Non-empty sequence ids whose row metrics should be read.<br><strong>Optional</strong>: `org_id` (str \| None; optional; default `None`): Optional workspace override for the row metrics read. | `sequence_row_metrics` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data.<br><strong>Common next calls</strong>: `vf.sequences.analytics` | read | installed SDK: `verbiflow/sequences.py:1585-1625` |
| `vf.sequences.run_audience_enrollment` | Use for explicit sequence draft, source staging, copy verification, personalization, publish, and transfer mutations. | <strong>Required</strong>: `sequence_id` (str; required): Sequence id whose published audience should be enrolled.<br><strong>Optional</strong>: `org_id` (str \| None; optional; default `None`): Optional workspace override for the enrollment write. | `sequence_audience_enrollment_status` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data.<br><strong>Common next calls</strong>: `vf.sequences.audience_enrollment_status` | platform_write | installed SDK: `verbiflow/sequences.py:1208-1244` |
| `vf.sequences.run_destination_sync` | Use to start a provider-writing manual destination sync for selected contacts, visible rows, or the full sequence audience after explicit confirmation. | <strong>Required</strong>: `sequence_id` (str; required): Verbiflow sequence id.<br><strong>Optional</strong>: `contact_ids` (list[str] \| None; optional; default `None`): Contact ids required for explicit/visible sync and forbidden when selection_mode='all'.; `force_create` (bool; optional; default `False`): When true, allow destination record creation instead of only updating/linking matches.; `org_id` (str \| None; optional; default `None`): Verbiflow organization/workspace UUID.; `selection_mode` (explicit \| visible \| all; optional; default `'explicit'`): Destination sync scope. Use 'explicit' with contact_ids for selected contacts, 'visible' with contact_ids for the current UI-visible subset, or 'all' for the whole sequence audience. | `sequence_destination_sync_run` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data. | provider_job_or_platform_write | installed SDK: `verbiflow/sequences_destination_sync.py:136-188` |
| `vf.sequences.run_destination_sync_schedule_now` | Use to run the configured scheduled destination sync immediately after confirming the sequence and provider scope. | <strong>Required</strong>: `sequence_id` (str; required): Verbiflow sequence id.<br><strong>Optional</strong>: `org_id` (str \| None; optional; default `None`): Verbiflow organization/workspace UUID. | `sequence_destination_sync_run` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data. | provider_job_or_platform_write | installed SDK: `verbiflow/sequences_destination_sync.py:190-218` |
| `vf.sequences.source_audience_counts` | Use for a cheap count of the current audience in one source ingress before paging or staging. | <strong>Required</strong>: `ingress_id` (str; required): Sequence ingress/source-instance id used when patching or staging a specific source.; `sequence_id` (str; required): Verbiflow sequence id.; `source_node_id` (str; required): Sequence source node id to preview, stage, upload, or update.<br><strong>Optional</strong>: `org_id` (str \| None; optional; default `None`): Verbiflow organization/workspace UUID. | `dict` with current audience display counts scoped to one sequence source ingress.<br><strong>Common next calls</strong>: `vf.sequences.source_audience_rows` | read | installed SDK: `verbiflow/sequences.py:2702-2736` |
| `vf.sequences.source_audience_rows` | Use for one bounded page of already-staged/materialized people for one source ingress. | <strong>Required</strong>: `ingress_id` (str; required): Sequence ingress/source-instance id used when patching or staging a specific source.; `sequence_id` (str; required): Verbiflow sequence id.; `source_node_id` (str; required): Sequence source node id to preview, stage, upload, or update.<br><strong>Optional</strong>: `cursor` (str \| None; optional; default `None`): Cursor parameter for `sequences.source_audience_rows`.; `limit` (int; optional; default `100`): Maximum number of records, preview rows, or results to request.; `org_id` (str \| None; optional; default `None`): Verbiflow organization/workspace UUID. | `dict` page with current materialized audience rows scoped to one source node ingress, including mapped cells, contact ids, provenance, total, and next cursor.<br><strong>Common next calls</strong>: `vf.sequences.source_audience_counts`, `vf.sequences.audience_rows` | read | installed SDK: `verbiflow/sequences.py:2573-2615` |
| `vf.sequences.source_audience_rows_all` | Use when source-scoped suppression needs all current rows and materializing them is acceptable. | <strong>Required</strong>: `ingress_id` (str; required): Sequence ingress/source-instance id used when patching or staging a specific source.; `sequence_id` (str; required): Verbiflow sequence id.; `source_node_id` (str; required): Sequence source node id to preview, stage, upload, or update.<br><strong>Optional</strong>: `max_rows` (int \| None; optional; default `None`): Maximum rows to upload, process, or return for this call.; `org_id` (str \| None; optional; default `None`): Verbiflow organization/workspace UUID.; `page_size` (int; optional; default `500`): Number of rows/results per page. | `dict` with source-scoped materialized audience rows combined across cursor pages, plus page and truncation metadata.<br><strong>Common next calls</strong>: `vf.sequences.source_audience_counts` | read | installed SDK: `verbiflow/sequences.py:2617-2657` |
| `vf.sequences.stage_artifact_to_source` | Use to attach durable artifact rows as a staged sequence source for explicit review. | <strong>Required</strong>: `artifact_id` (str; required): Artifact id whose rows should be staged for review.; `sequence_id` (str; required): Sequence id to stage into.; `source_node_id` (str; required): Sequence source node id that receives staged artifact rows.<br><strong>Optional</strong>: `column_mapping` (JsonObject \| None; optional; default `None`): Full LeadImportColumnMappingPayload objects keyed by target variable. Do not pass CSV shorthand mappings for artifact staging.; `idempotency_key` (str \| None; optional; default `None`): Idempotency key parameter for `sequences.stage_artifact_to_source`.; `ingress_id` (str \| None; optional; default `None`): Sequence ingress/source-instance id used when patching or staging a specific source.; `mapping_source` (str; optional; default `'explicit'`): Column-mapping provenance accepted by sequence staging: explicit or producer.; `org_id` (str \| None; optional; default `None`): Verbiflow organization/workspace UUID.; `row_keys` (list[str] \| None; optional; default `None`): Row keys parameter for `sequences.stage_artifact_to_source`. | `dict` with staged source rows, mapping status, warnings, idempotency/provenance metadata, and promote-ready state for artifact-backed staging. | platform_write | installed SDK: `verbiflow/sequences.py:3730-3805` |
| `vf.sequences.step_occupancy` | Use for explicit sequence draft, source staging, copy verification, personalization, publish, and transfer mutations. | <strong>Required</strong>: `sequence_id` (str; required): Sequence id whose per-step occupancy should be read.<br><strong>Optional</strong>: `org_id` (str \| None; optional; default `None`): Optional workspace override for the occupancy read. | `sequence_step_occupancy` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data.<br><strong>Common next calls</strong>: `vf.sequences.analytics`, `vf.sequences.advanced_people` | read | installed SDK: `verbiflow/sequences.py:1659-1700` |
| `vf.sequences.transfer` | Use to move or assign a sequence/lead list to another owner or workspace-supported target. | <strong>Required</strong>: `sequence_id` (str; required): Verbiflow sequence id.; `target_org_slug` (str; required): Target org slug parameter for `sequences.transfer`.<br><strong>Optional</strong>: `org_id` (str \| None; optional; default `None`): Verbiflow organization/workspace UUID. | `dict` with sequence transfer status, source/target owner/workspace ids, and validation messages. | platform_write | installed SDK: `verbiflow/sequences.py:3351-3385` |
| `vf.sequences.update_assignments` | Use to replace sequence assignees; pass `expected_assignments_version` when known or let the SDK read the current version. | <strong>Required</strong>: `sequence_id` (str; required): Verbiflow sequence id.; `user_ids` (list[str]; required): Workspace user ids that should replace the sequence assignee list.<br><strong>Optional</strong>: `expected_assignments_version` (int \| None; optional; default `None`): Optimistic concurrency token. Omit to let the SDK read the current sequence assignments_version before saving.; `org_id` (str \| None; optional; default `None`): Verbiflow organization/workspace UUID. | `dict` with sequence draft/published state, steps, sources, version, and routing metadata. | platform_write | installed SDK: `verbiflow/sequences.py:818-869` |
| `vf.sequences.update_destination_sync_config` | Use to save sequence-owned destination sync settings; SDK strips read-only config fields returned by `destination_sync_config`. | <strong>Required</strong>: `config` (JsonObject; required): Destination sync config object. It may come from destination_sync_config()['config']; the SDK sends only writable HubSpot config fields and strips read-only fields such as config_id and updated_at.; `sequence_id` (str; required): Verbiflow sequence id.<br><strong>Optional</strong>: `org_id` (str \| None; optional; default `None`): Verbiflow organization/workspace UUID. | `sequence_destination_sync_config` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data. | platform_write | installed SDK: `verbiflow/sequences_destination_sync.py:70-101` |
| `vf.sequences.update_revision_adoption_policy` | Use to change whether the sequence auto-adopts compatible revisions after confirming the sequence. | <strong>Required</strong>: `auto_adopt_compatible_revisions` (bool; required): Auto adopt compatible revisions parameter for `sequences.update_revision_adoption_policy`.; `sequence_id` (str; required): Verbiflow sequence id.<br><strong>Optional</strong>: `org_id` (str \| None; optional; default `None`): Verbiflow organization/workspace UUID. | `dict` with sequence draft/published state, steps, sources, version, and routing metadata. | platform_write | installed SDK: `verbiflow/sequences.py:895-928` |
| `vf.sequences.upload_attachment` | Use for explicit sequence draft, source staging, copy verification, personalization, publish, and transfer mutations. | <strong>Required</strong>: `file_path` (str \| Path; required): Absolute path to an existing file no larger than 20MB.; `kind` (pdf \| video \| email_attachment; required): Attachment category expected by the sequence builder.; `sequence_id` (str; required): Sequence id associated with the attachment upload.<br><strong>Optional</strong>: `org_id` (str \| None; optional; default `None`): Optional workspace override for the object-storage write. | `sequence_attachment_upload` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data.<br><strong>Common next calls</strong>: `vf.sequences.attachment_preview_url` | platform_write | installed SDK: `verbiflow/sequences.py:2220-2282` |
| `vf.sequences.upload_csv_to_source` | Use to upload a local CSV, stage it into a sequence source, and promote the staged source run with explicit column mapping. | <strong>Required</strong>: `csv_path` (str \| Path; required): Absolute local filesystem path.; `sequence_id` (str; required): Verbiflow sequence id.; `source_node_id` (str; required): Sequence source node id to preview, stage, upload, or update.<br><strong>Optional</strong>: `column_mapping` (JsonObject \| None; optional; default `None`): Column mapping configuration. CSV upload accepts simple target variable -> source column mappings; artifact staging must use full mapping payload objects.; `file_label` (str \| None; optional; default `None`): Label to attach to the uploaded/staged file.; `idempotency_key` (str \| None; optional; default `None`): Idempotency key parameter for `sequences.upload_csv_to_source`.; `ingress_id` (str \| None; optional; default `None`): Sequence ingress/source-instance id used when patching or staging a specific source.; `list_label` (str \| None; optional; default `None`): Label to use for the staged sequence source/list.; `mapping_source` (str \| None; optional; default `None`): Column-mapping provenance accepted by sequence staging: explicit or producer.; `org_id` (str \| None; optional; default `None`): Verbiflow organization/workspace UUID.; `override` (bool; optional; default `False`): When true, promote replaces matching draft audience rows that have not entered this sequence runtime. Default false keeps existing audience rows and annotates uploaded duplicates.; `require_contact_identifier` (bool; optional; default `True`): When true, fail before staging if a CSV has no email or LinkedIn/profile contact identifier column. | `dict` with CSV staging result plus `csv_path`, `row_count`, `source_run_id`, `promote_status`, and `promote_result`. Preserve source/import handles. | platform_write | installed SDK: `verbiflow/sequences.py:3807-3916` |
| `vf.sequences.validate_destination_sync_config` | Use to validate destination sync settings before saving them. | <strong>Required</strong>: `config` (JsonObject; required): Destination sync config object. It may come from destination_sync_config()['config']; the SDK sends only writable HubSpot config fields and strips read-only fields such as config_id and updated_at.; `sequence_id` (str; required): Verbiflow sequence id.<br><strong>Optional</strong>: `org_id` (str \| None; optional; default `None`): Verbiflow organization/workspace UUID. | `sequence_destination_sync_validation` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data. | read | installed SDK: `verbiflow/sequences_destination_sync.py:103-134` |
| `vf.sequences.webhook_source_key` | Use for explicit sequence draft, source staging, copy verification, personalization, publish, and transfer mutations. | <strong>Required</strong>: `ingress_id` (str; required): Webhook source ingress id whose key should be read.; `sequence_id` (str; required): Sequence id that owns the webhook source ingress.<br><strong>Optional</strong>: `org_id` (str \| None; optional; default `None`): Optional workspace override for the webhook key read. | `sequence_webhook_source_key` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data.<br><strong>Common next calls</strong>: `vf.sequences.ingest_webhook_rows` | read | installed SDK: `verbiflow/sequences.py:2098-2140` |
<!-- END GENERATED: core-sdk-surfaces -->

## Data Contracts

### IDs And URLs

- `sequence_id` is the stable sequence handle.
- Sequence URLs are shaped `https://platform.verbiflow.com/w/<org-slug>/sequences/<sequence_id>/<view>`
  where `<view>` is one of `builder`, `audience`, `analytics`, `settings` (and
  the bare `/w/<org-slug>/sequences` lists sequences for that workspace).
  The `/w/<org-slug>` segment is the authoritative workspace pointer. Split
  on `/w/` and take the next path segment to recover the `org_slug`, then
  resolve to `org_id` via `vf.auth.list_workspaces()`. Pass that as
  `org_id=...` to `vf.sequences.*` instead of re-focusing the workspace.
- `builder_url`, `audience_url`, `analytics_url`, `settings_url`, and
  `app_url` are attached by the SDK when the active client has an org slug.
- Draft mutations use optimistic version handles. Preserve `draft_id` and
  `expected_draft_version` from detail payloads when you already have them.
- Source-scoped operations need `source_node_id`; many also need `ingress_id`
  when there are multiple source instances.
- Staging/import verification depends on `lead_list_id`, `source_run_id`, and
  `import_id` when returned.

### Audience Paging

- `audience_rows(...)` and `source_audience_rows(...)` return one bounded page.
- `audience_rows_all(...)` and `source_audience_rows_all(...)` intentionally
  materialize pages into memory and report `page_count`, `returned`,
  `truncated`, and continuation cursor metadata.
- `iter_audience_rows(...)` and `iter_source_audience_rows(...)` are the
  default suppression path for large active sequences.
- The backend page size is capped. A single `audience_rows(limit=100)` call is
  never sufficient duplicate suppression for a large sequence.
- Audience delete, hold, and release calls use one selection rule: pass either
  non-empty `contact_ids` or `all_rows=True`, never both and never neither.

### Import Rows And Analytics

- `import_rows(...)` returns one bounded page for one `lead_list_id`. Rows carry
  column-aligned `cells` plus `columns`; do not assume a fixed named-field
  shape.
- `import_rows_all(...)` and `iter_import_rows(...)` use the same non-advancing
  cursor guard as audience paging.
- Advanced analytics list routes use opaque cursors. `limit` is clamped by the
  backend to 1..500.
- `advanced_summary(..., from_time=..., to_time=...)` maps those ISO 8601
  strings to query parameters named `from` and `to`.

### Webhooks And Attachments

- `webhook_source_key(...)` returns `key`, `header_name`, `ingress_id`, and
  `sequence_id`; it does not return a URL.
- `ingest_webhook_rows(...)` sends the key in the returned header name, normally
  `X-Flage-Webhook-Key`, and posts `{"contacts": [...]}`. The ingest route
  upserts staged rows by identifier.
- `upload_attachment(...)` returns `s3_key` as the stable handle to put in
  sequence step payloads.
- `attachment_preview_url(...)` returns a short-lived URL and
  `expires_seconds`; never cache the URL as the attachment handle.

### Staging Inputs

- CSV staging requires an absolute `csv_path`.
- `upload_csv_to_source(...)` accepts simple target-variable to source-column
  mappings, validates contact identifier columns by default, stages the CSV,
  then promotes the staged source run.
- `stage_artifact_to_source(...)` accepts durable artifact rows and requires
  full `LeadImportColumnMappingPayload` objects in `column_mapping`; do not pass
  CSV shorthand mappings.
- Use `mapping_source="explicit"` for human/agent-authored mappings and
  `mapping_source="producer"` only when the upstream producer emitted the
  mapping.
- Use stable idempotency keys for retries. The SDK generates one for artifact
  staging when omitted; CSV upload accepts an explicit non-empty key.
- `upload_csv_to_source(..., override=False)` is the default and keeps existing
  sequence audience rows. Use `override=True` only after the operator explicitly
  chooses replacement for this upload; it sends `override_existing` only on the
  promote request, replacing matching draft audience rows that have no sequence
  runtime history. It does not overwrite enrolled or historical sequence runs.

### Publish

- Call `vf.sequences.publish_diff(sequence_id)` before publish to read the
  unpublished changes: the structured diff between the live saved draft and the
  currently published revision. It is a pure read with no side effects. Show the
  summary and changes to the operator so publish confirmation covers exactly
  what will go live.
- `vf.sequences.revisions(sequence_id)` lists the sequence's published version
  history; use it to discover the revision ids and numbers to feed
  `vf.sequences.revision_diff(...)`.
- `vf.sequences.publish(...)` fetches current draft metadata when `draft_id` or
  `expected_draft_version` are omitted.
- `activate_sequence=False` is the SDK default, matching the frontend publish
  flow. Pass `activate_sequence=True` only when the user explicitly wants the
  sequence published and activated in the same operation.
- Publish is not a copy-review shortcut. Use `sequence_authoring.md` for copy
  verification, then run sender checks before activation.

## Examples

### Suppress Against The Current Audience

```python
import verbiflow as vf

vf.auth.ensure_logged_in()

matches = vf.sequences.list(state="active", q="Expansion")
sequence = vf.sequences.get(matches["sequences"][0]["sequence_id"])
sequence_id = sequence["sequence_id"]

existing_emails = {
    str(row.get("email") or "").strip().lower()
    for row in vf.sequences.iter_audience_rows(sequence_id=sequence_id, page_size=500)
    if str(row.get("email") or "").strip()
}
print(sequence_id, len(existing_emails), sequence.get("audience_url"))
```

### Stage A Reviewed CSV

```python
from pathlib import Path

import verbiflow as vf

csv_path = Path("/absolute/path/to/reviewed_rows.csv")
result = vf.sequences.upload_csv_to_source(
    csv_path=csv_path,
    sequence_id="seq_...",
    source_node_id="n_source",
    column_mapping={
        "email": "email",
        "first_name": "first_name",
        "company_name": "company_name",
        "personalization_note": "personalization_note",
    },
    idempotency_key=f"reviewed-csv:{csv_path.name}",
)
print(result.get("source_run_id"), result.get("lead_list_id"), result.get("row_count"))
```

## Verification

- After list/get: confirm `sequence_id`, status/state, draft version,
  `builder_url`, and `audience_url`.
- After source or AI-filter preview: inspect counts, sample rows, partial
  status, `filter_run_id`, `after_seq`, and filter reasons before saving.
- After staging: check `source_run_id`, `lead_list_id`, row count, promotion
  status, mapping warnings, imports, and source-scoped audience rows.
- After personalization/enrichment writes handled via `copy.md`:
  re-read the affected audience/source rows here and verify exact variables or
  notes changed.
- After publish: call `get(sequence_id)` and confirm the published/active state
  and audience count. `vf.sequences.publish_diff(sequence_id)` should now report
  `is_current: true` with no remaining changes. If this came from a workflow, sync the Workflow Play again
  with `vf.workflows.sync(...)` after the mutation.

## Troubleshooting

| Symptom | Likely Cause | Fix |
| --- | --- | --- |
| Duplicate suppression missed people already in the sequence. | Only one bounded `audience_rows(...)` page was read. | Use `iter_audience_rows(...)`, `audience_rows_all(...)`, or source-scoped equivalents. |
| CSV staged but audience looks unchanged. | Wrong source node/ingress, mapping warnings, promotion/import failure, or source rows have not materialized into the audience yet. | Inspect `promote_status`, `promote_result`, `imports(...)`, `import_status(...)`, `source_audience_counts(...)`, and source-scoped rows. |
| Artifact staging mapping fails. | CSV shorthand mapping was passed to artifact staging. | Use full `LeadImportColumnMappingPayload` objects for `stage_artifact_to_source(...)`. |
| AI-filter preview returned partial rows. | Worker still running, heartbeat stalled, or timeout hit. | Continue polling `ai_filter_preview_status(...)` with `filter_run_id` and `after_seq`. |
| Personalization writes affected too much. | Sequence personalization calls were used without following `copy.md` dry-run and confirmation rules. | Stop and audit exact affected contacts/rows; use `copy.md` for repair semantics. |
| Publish started enrollment/sending unexpectedly. | The caller explicitly passed `activate_sequence=True`, or activation happened separately after publish. | Require confirmation immediately before activation; omit `activate_sequence` or pass `activate_sequence=False` for publish-without-activation. |
| Enrollment status returned 404. | Sequence missing, no published revision, or no enrollment run exists yet. | Confirm sequence/org, publish state, and whether enrollment has ever been queued. |
| Enrollment trigger returned 409. | Enrollment is already running. | Read `audience_enrollment_status(...)`; do not retry until the active run terminalizes or is cancelled. |

## Related References

| Reference | Use For |
| --- | --- |
| `sequence_authoring.md` | Draft source/filter/copy/step design and source/AI-filter previews. |
| `row_operations.md` | Local row shaping, variable coverage, CSV transforms, and deterministic cleanup before staging. |
| `artifacts_jobs.md` | Waiting for jobs, preserving artifact ids, paging artifact rows, and artifact-to-sequence staging context. |
| `audience_discovery.md` | Provider-backed people/account discovery before a sequence exists. |
| `crm.md` | CRM-backed suppression, associations, active customer/deal checks, and routing inputs. Not destination-sync writes. |
| `copy.md` | Copy guidance, personalization job design, sequence personalization runs, notes, enrichment writes, and runtime-refresh boundaries. |
| `senders.md` | Sender readiness, mailbox/domain setup, sender matching, and sandbox checks. |
| `workflow_operations.md`, `workflow_schedules.md` | Running/repairing generated Workflow Plays, then syncing their canonical revisions/outputs. |
