> ## Documentation Index > Fetch the complete documentation index at: https://docs.octavehq.com/llms.txt > Use this file to discover all available pages before exploring further. # What are Motions in Octave? > Motions are the GTM strategies your team executes — a complete plan combining an offering, a target market, narrative angles, and persona×segment ICPs that agents read at runtime. ## What is a Motion? A Motion is a complete go-to-market strategy in the [Octave Library](/concepts/library) — the unit your team actually executes against. It binds an [offering](/concepts/offerings) to a market motion type (new business, expansion, renewal, displacement), a set of narrative angles ([Motion Playbooks](#motion-playbooks)), and the persona×segment cells that detail who you're selling to and how ([Motion ICPs](#motion-icps)). When an agent generates an email, qualifies an account, or preps a call, it traverses the Motion to read the right narrative for the right audience — grounded in your strategy, not generic templates. Motions replace the legacy [Playbook](/concepts/playbooks) entity. Where a legacy Playbook was a single flat object, a Motion is a structured hierarchy: one Motion → many Motion Playbooks (narrative angles) → many Motion ICPs (persona×segment cells). Each layer is independently editable, learnable, and addressable by agents and the API. ## What a Motion contains | Field | Purpose | | - | - | | Name | Internal name for the strategy | | Description | What this Motion is selling and why now | | Offering | The [Product](/concepts/offerings), [Service](/concepts/services), or [Solution](/concepts/solutions) being sold | | Motion type | `NET_NEW`, `UPSELL`, `CROSS_SELL`, `CONVERT_FREE_TO_PAID`, `RENEW_AND_RETAIN`, `DISPLACE_INCUMBENT` | | Overview | High-level strategy summary | | Additional context | Free-form context the agents should know | | Attached sources | URLs, docs, or resources informing the strategy | | Default playbook | The Motion Playbook used when no specific angle is selected | ## Motion Playbooks A Motion Playbook is a narrative angle within a Motion — a specific way of framing the same offering to a specific audience or moment. A single Motion typically contains several Motion Playbooks, each with its own narrative type: | Narrative type | When to use it | | - | - | | `DEFAULT` | Baseline narrative for the Motion | | `THEMATIC` | Built around a theme, trend, or category point of view | | `MILESTONE` | Triggered by an event in the account's life (funding, hiring, launch) | | `ACCOUNT` | Targeted at a single named account | | `COMPETITIVE` | Displacement angle against one or more [competitors](/concepts/competitors) | `DEFAULT` is set automatically on the playbook created with each Motion and isn't a user-creatable type — when calling `POST /api/v2/motion-playbook/create`, the `narrativeType` enum is restricted to `THEMATIC`, `MILESTONE`, `ACCOUNT`, or `COMPETITIVE`. A Motion Playbook owns the messaging that agents actually deploy: | Field | Purpose | | - | - | | Name | Internal name for the angle | | Narrative type | One of the types above | | Narrative input | The seed idea, theme, or framing | | Motion framing | How to position this angle | | Key messaging | Bullet messages agents pull from | | Key positioning | How to differentiate inside this angle | | Scope | Which [segments](/concepts/segments) and [personas](/concepts/personas) this playbook applies to (AUTO or MANUAL) | | Anchor overrides | Per-playbook override of which [use cases](/concepts/use-cases), [proof points](/concepts/proof-points), [references](/concepts/references), [alternatives](/concepts/alternatives), and [objections](/concepts/objections) to pull from | | Competitor / account / buying trigger refs | The competitor(s), account domain, or [buying trigger](/concepts/buying-triggers) this angle targets | ## Motion ICPs A Motion ICP is the intersection of one [persona](/concepts/personas) and one [segment](/concepts/segments) inside a Motion Playbook's scope — the smallest addressable cell in the strategy. Each Motion ICP holds the narrative, learnings, and recommended library elements for that exact persona×segment cell. ### Narrative Each Motion ICP carries a structured narrative the agents read: * **Target ICP overview** — who this cell is * **Operating landscape** — the world they live in * **Strategic narrative** — the story you're telling them * **Pains and consequences** — what hurts if they don't act * **Benefits and impacts** — what changes if they do * **Methodology** — the structured discovery / qualification path * **References** — the relevant customer stories to cite ### Learnings Octave continuously generates learnings on each Motion ICP from real conversations: | Learning type | What it captures | | - | - | | `KEY_LANGUAGE` | Vocabulary this audience uses | | `INDUSTRY_TREND` | Shifts shaping their world | | `PAIN_POINT` | Recurring problems heard in the field | | `VALUE_PROP` | Benefits that landed in calls and emails | | `OBJECTION` | Pushback raised in deals | Each learning carries a confidence score, a source (`AI_GENERATED` or `USER_DEFINED`), evidence counts per channel, and a pin status so your team can lock in the ones that matter. Learnings flow from the [analytics](/concepts/analytics) pipeline directly into the Motion ICP that produced them. ### Recommended elements Octave recommends which existing [Library](/concepts/library) entities to attach to a Motion ICP — [use cases](/concepts/use-cases), [proof points](/concepts/proof-points), references, [competitors](/concepts/competitors), [alternatives](/concepts/alternatives), [buying triggers](/concepts/buying-triggers), and [objections](/concepts/objections). The agent uses these recommendations at runtime so the right evidence shows up for the right cell. ### Keeping cells up to date A Motion ICP's narrative is generated from its inputs: the persona, segment, offering, Motion, Motion Playbook, segment intel, sales methodology, brand voice, and the learnings gathered so far. When any of those changes after the cell was generated, the cell is **stale**: it still works, but it no longer reflects your latest strategy. Octave tracks this for you. Each cell reports whether it is stale, why (for example `parent_persona_updated`, `competitor_updated`, or `new_learnings`), and which element changed and when. A cell that was never generated is stale too. To refresh one, regenerate it: Octave writes a new version from its current inputs, at the same credit cost as updating the cell in the app. ## How agents use Motions When you run an agent — a Sequence Agent, Call Prep Agent, or Qualify Person Agent — it identifies which Motion applies based on the offering and the prospect's persona and segment. It then selects the right Motion Playbook (default, competitive, account-specific, etc.), and from there reads the Motion ICP narrative, learnings, and recommended elements for that persona×segment cell. The same agent produces dramatically different output for an Enterprise CFO in healthcare and a mid-market SDR Manager in fintech, because the Motion routes each prospect to a different cell. ## Managing Motions via API * `GET /api/v2/motion/list` — list motions * `GET /api/v2/motion/get` — get a motion with its default playbook * `POST /api/v2/motion/create` — create a motion (and its default playbook) * `POST /api/v2/motion/update` — update a motion * `DELETE /api/v2/motion/delete` — delete a motion * `GET /api/v2/motion-playbook/list` / `get` / `POST create` / `POST update` / `DELETE delete` — manage Motion Playbooks * `GET /api/v2/motion-icp/list` — list Motion ICP cells under a playbook; pass `includeStaleness=true` to see which are stale, or `staleOnly=true` to list only those * `GET /api/v2/motion-icp/get` — get the full Motion ICP detail (narrative, status, and staleness) * `POST /api/v2/motion-icp/regenerate` — regenerate a cell from its current inputs (can take a minute or more) * `GET /api/v2/motion-icp/elements/list` — list recommended library elements for a Motion ICP * `GET /api/v2/motion-icp/learnings/list` — list learnings for a Motion ICP * `GET /api/v2/motion-icp/learnings/get` — get a single learning This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.