> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heralded.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Actions

> The work that changes what AI says about you, who holds it, and how you know it paid off.

An action is one piece of work meant to change the answers, such as fixing a page, writing a piece or pitching a source. Heralded suggests actions from what each report finds, and you can add your own. The **Actions** page holds them all.

Findings that ask for the same output on the same target share one action, with their evidence combined. Your homepage's structured-data checks share one site fix. A page update and an outreach pitch stay separate, even when they address the same prompt. Duplicate suggestions are withdrawn on the next weekly report. Work you have started stays in place.

The things-to-do count includes all open actions, including work carried over from earlier reports, and excludes setup items. Home, Team activity, Actions and the Board use this count. A completed report keeps the count from when its counters finished.

Select a task card anywhere in the Command Center to open its pane on the page you are reading. The address names the open task and keeps your page filters. Closing the pane returns to that page. **Start** opens the same pane with the credit cost, approval requirements and start confirmation.

## The week

At the top, the autonomy line links to the brand's [Autonomy settings](/concepts/autonomy). On Core, the line beside it counts the week's [tasks](/concepts/usage#brands-and-segments), such as **5 a week on Core · 3 started**. The weekly sentence shows the answers and pages read and tasks finished in the last seven days. Its proposed count is the current open work. A finished task is delivered, counted once. Clauses with no activity are omitted. Dismissed tasks, setup and prompt tracking are excluded from team task counts.

The byline's live dot appears while a job is running, including the Herald's runs. **Overview** is selected by default. Use **Board** to open the team's tasks; both tabs keep their own address, so you can use the browser's back button to return.

**Team activity**, beside **Ready for your review**, shows the team's work under **Now** and **Next**. Each line has its member's mark and opens the job. **All work** leads to the board. **Review all** opens review mode when work is ready for your decision. Home's **Team activity** also shows **Done**.

**Ready for your review** shows one card per decision. Each card names the member, shows when the preparation finished if recorded, and previews the draft's opening lines, an email's recipient and subject, or the planned change. The line below describes your next step. **Review**, **Approve** or **Read and send** opens the task's existing controls to read the full result and decide. A content draft's **Review** opens that piece's own page. Drafts still being checked appear once they are ready for your review. No change is applied or email sent by opening a card. When the queue is empty, it says **Nothing to review.**

## The team

The Writer, Publicist and Engineer each have a card showing their name, a count of their new, working and done tasks, a measure and up to three tasks. The measures link to the pages they describe:

| Member | Measure |
| - | - |
| Writer | **Topics covered**, from [Content](/concepts/content) |
| Publicist | **Cited sites that name you**, from [Sources](/concepts/sources) |
| Engineer | **Pages AI can read**, from [Website](/concepts/site-readability) |

Each measure shows its value out of the total, with a bar. An unmeasured figure says **Not measured**. When a comparison with your first report is available, the card shows it below the bar.

Task lines appear in this order: running now, your turn, proposed and the latest delivered. Each shows its state in words and opens the task. The count under the name covers new, working and done tasks for the Writer and Engineer. The Publicist counts waiting tasks in place of working tasks.

**Open** on a card opens that member's pane. It shows the member's mission and measure, with a note on what is left: topics with no page, cited sites that don't name you yet, or pages AI can't read. **New** lists up to four proposed tasks in the brand's order. **Working on** lists up to four open tasks: work under way first, then your turn, then work waiting on others. **Recently done** lists the two latest deliveries. Select a task to open its pane, and use the member's name at the top to go back. The link below them, such as **All 12 of the Writer's tasks, done included ›**, opens the board filtered to that member. It counts every task except dismissed ones.

The Herald speaks as "I" for its own work and "we" for the team.

The Herald row shows the answers read, pages read and actions found in the last seven days, and the competitors the brand tracks. Below its mission and counts, you can see current runs with their progress and the next scheduled runs. When the brand is paused or read-only, the row shows that notice.

The Herald's runs are the daily update, the weekly report and three more. The **Site check** checks the pages of your site and adds them to your inventory. The **Brand-mention check** lists the pages on your site and your competitors' sites and rereads the ones it watches for changes. The **Competitor search** searches the web on the topics you track and adds new pages that mention them to your sources.

## Proposed

The table shows every unstarted team task, five per page, in the brand's order. Tasks you place come first, followed by tasks Heralded ranks by severity and reach. The line above counts tasks by type across all pages. Each row shows **Task**, **Page** and **Type**, with its short reason and content-credit cost when it spends one. **Page** shows the URL path, with the full address on hover. Select the task to read its full pane. When you can start work, each row has a checkbox at its left edge that starts checked. **Not now** dismisses that row. Uncheck any tasks you do not want to start in this page's batch.

The **All** link shows the total and opens **Proposed** on the board. The primary button shows how many tasks are checked on the current page, such as **Start 3**, or **Start all 5** when every task is checked, and opens a confirmation for only those tasks. The confirmation shows the content-credit total and each task's start timing. It also says how many tasks will wait for your approval. Nothing starts until you confirm.

The server checks permission, the active plan, credits and Autonomy again when you confirm. Each task starts independently. A refused task stays in the table with the reason while it is still proposed. Tasks waiting for Undo on the board are left out of proposals. If a selected task starts waiting for Undo, check the remaining proposals again before confirming. You can restore a dismissed task from the board.

## The board

Drag a proposed card to set the order everyone sees. The top is the first priority. Placing a task also fixes the tasks above it. Heralded ranks the tasks nobody placed, below **Heralded ranks the rest.** With the keyboard, Alt+Up and Alt+Down move a focused card. On a phone, choose **Move to top** in its menu.

The board has its own address, reached from the **Board** tab or **All work** in **Team activity**. Choose **Overview** to return to the week's work.

Filter by **Team member** and **Owner**, and by **Segment** when your brand has more than one. **Team member** and **Owner** start on **All**, and **Owner** also offers **Mine**. The board opens on **All segments**. The address keeps your filters, so you can share or reload the same view. **Mine** shows tasks assigned to you. Turn on **Dismissed** to find dismissed tasks, open one and choose **Restore** in its pane. Restore, and Undo on the dismissal toast, put the task back where it was, with its draft. A content order that had not produced a piece returns as proposed, and its credit is charged again if you start it again.

| Column | Holds |
| - | - |
| Proposed | work you have not started, including scheduled tasks with their start date |
| Working | work Heralded is carrying out, and the Herald's runs still to come |
| Your turn | work waiting on a decision or a step from you |
| Waiting on others | work waiting on someone outside, such as a reply to a pitch |
| Done | delivered tasks and the Herald's finished runs from the last 30 days, newest first |

Cards show the member, the task's title and one line about the work. A setup task has no member and shows **You**. Open a card for its detail and controls. **Proposed** and **Your turn** cards show their buttons. Dismissed tasks are hidden unless **Dismissed** is on. The **Actions** badge counts the work waiting on you in **Your turn**. A dot beside it means Heralded has proposed tasks since you last opened Actions.

**Proposed** groups the tasks Heralded ranks by kind, such as **Content updates 15**, showing the first task. **See 14 more** opens the rest in place. **Start all** starts every task in the group after the same confirmation as **Start all** on Actions.

The month's results use settlement dates in that calendar month, in UTC. Credited Mentioned gains, live site fixes and measured no-move results count. Inconclusive results do not. All segments count unless you filter by segment. The weekly email uses the same population for the month of its report.

**Working**, **Your turn** and **Waiting on others** have page numbers below their cards when they are long. **Done** uses **Older ›** and **‹ Newer** to move through deliveries. Each column moves independently. On a phone, swipe between columns or choose one from the tabs above the board.

## Kinds of work

| Kind | What it is |
| - | - |
| Site fix | a technical change, such as robots.txt, structured data or llms.txt |
| Content update | a rewrite of an existing page, or of its title and description |
| New content | a new piece, written in [Content Studio](#content-studio) |
| Outreach | reaching a site the engines cite, in one of the [four ways below](#outreach) |
| Correction request | a request to fix something wrong a source says about you |
| Competitor gap | a topic where engines name competitors and not you |
| Setup | a one-time setting or connection suggested after your first weekly report, listed in [Get started](/get-started#your-first-week) |

Heralded leaves at most five untouched suggestions each for site fixes, competitor gaps, prompt content updates and new content. Page title and description updates have five places across all open work. Starting work keeps it in place. Past these limits Heralded files no new suggestions of that kind until you decide on some. It never takes back one you can see. When a weekly report no longer finds the issue behind a suggestion, the suggestion stays in **Proposed**, marked **Not in the latest weekly report**, until you start it or choose **Not now**.

Prompts worth tracking appear in [Prompts › Discover](/concepts/prompts#the-prompts-page). Choose **Track** there to add one to your tracked set.

Not every finding becomes an action. A competitor newly named in your answers is announced under **Changes** on Home, as [Competitors](/concepts/competitors) describes, and files no action. A prompt you lose appears there too, and becomes an action only once the loss has held for three daily updates or weekly reports in a row. The action names the engines and the pages they cited before the loss.

## Task metadata in the API

### Team conversations

The Herald, Writer, Publicist and Engineer each have one standing conversation per brand, shared by everyone who can read the brand. Posting needs permission to start work. Your unread count is the number of messages after your own read position. That position only moves forward.

Select **New chat** under **Chats** to start a private chat with the Herald. Only you can read it, including when another person owns or administers the workspace. The title comes from your first message. Use **Rename** in the chat's menu to change it.

**Share** makes the chat readable and postable by everyone who can read the brand. Sharing includes the messages already in the chat. You cannot make it private again. Viewers can start chats, post in shared chats and get answers, but cannot confirm a proposal that changes your brand or starts work.

The chat's creator can choose **Archive** in its menu. The chat then stays readable in **All chats**, with posting closed. There is no delete command. The rail shows the eight most recent unarchived chats below the standing conversations. **All chats** also includes older and archived chats you can read. Standing conversations cannot be archived.

The Herald answers every message in a private chat. In shared conversations, it decides when a message is meant for it. Answer limits apply per person and per brand, alongside your organization's [monthly answer allowance](/concepts/usage#agent-answers). One person's refused requests do not use another person's answer slots.

Erasing your account deletes your private chats. Messages you posted in shared conversations remain attributed to **A teammate**, with their text removed.

The task's owner posts an update when a draft is ready, approval or brief answers are needed, work is blocked, a draft, start or site write fails, a change lands on the site, a piece is published, or a result is checked. A piece's first AI citation also gets an update. Drafts prepared ahead of time are announced only after you start the task. A failure that blocks work gets one update. Other steps stay in the task timeline.

New messages appear while the conversation is open, and it catches up when your connection returns. While a member prepares an answer, you see **Reading your brand…**. The status clears when the complete answer arrives or the attempt fails.

Mentioning a member or replying to one of its messages asks it for an answer. A message that mentions only colleagues leaves the member silent. For other messages, Heralded decides whether the member is being asked something. A colleague you mention gets an email linking to the conversation, unless they turned off **Needs your approval** in **Notifications**. The mention counts as unread for them.

An answer quotes the message it responds to and can propose starting or scheduling a task, moving it to the top, tracking or pausing a prompt, adding or removing a competitor, requesting draft changes, filing a correction or page fix, or ordering content. The card shows the change, its target and what it uses. An order shows its content credit cost.

Select **Confirm** to run the change with your permissions. Heralded checks the current limits and conditions when you confirm. A confirmed card keeps its result, so retrying the click makes no further change. Viewers can read cards but cannot confirm them. **Not now** hides the card and leaves the task untouched.

Corrections need an observed claim and its passage. Page fixes need a current audit finding. When evidence is missing, the teammate asks for it or declines. Both filings stay **Proposed** until you start them. A content order starts when you confirm it. **Start** inside a report or update starts the named task directly.

**Request changes** revises a short draft or adds a comment included in the next rewrite of a long-form draft. It applies only to the draft version the member suggested changes to. The long-form comment links back to its proposal. If the comment's confirmation is interrupted, retrying recovers that comment. While Heralded cannot establish whether it was saved, the card stays unconfirmed and sends no additional comment.

The Herald answers questions about the whole brand and can suggest changes to any member's tasks. When you ask it for specialist work, it passes your request to the Writer for content, the Publicist for outreach or the Engineer for site fixes. The specialist answers as itself in its own conversation. Passing a request starts no task and changes no work.

Every member reads only that brand's data. It cannot read organization data or other conversations. It can read a current draft, judge it, quote a short fragment and propose changes in words. If the task supports revisions, it offers **Request changes** for a rewrite, with the proposal as its note. Replacement copy is written in the draft review, where revision limits and content credits apply. The conversations are served through the app's API.

Select the Herald, Writer, Publicist or Engineer under **Chats** in the rail to open the whole conversation in a column beside it. You can also select **Open** at a teammate's desk on Actions. The whole page dims behind the column, and the rail stays usable above it. The conversation starts at your read position, or at the newest messages when you have read everything. **Earlier messages** and **Newer messages** let you move through a longer thread. Every message stays separate, including consecutive answers from the same member. A conversation link opens the same column. The rail's unread count falls as you read messages in view.

At 1360px and wider, select **Split with the page** in the conversation header to keep the page interactive beside it. Heralded remembers your choice in this browser. Select **Back over the page** to return to the overlay.

Task chips and links to prompts, competitors or answers open their detail in the right pane beside the conversation, and you can keep writing in the conversation while the pane is open. In the overlay, press Escape or use Back to close that pane, then again to close the conversation. A page link navigates there and closes the overlay conversation; in split mode, the conversation stays open. Clicking the dimmed page closes the pane first, then the conversation. On a phone the conversation fills the screen.

The task pane offers **Ask the Writer**, **Ask the Publicist** or **Ask the Engineer**. It opens that teammate's whole conversation with the task attached under **Looking at**, and the pane stays open beside it. With a pane open, you can also open any conversation from the rail. Opening a conversation from a page attaches that page instead. You can remove the context before sending. Everyone in the conversation sees it under your sent message.

Type # or select **# Task** to search tasks by title, owner or state. Use the arrow keys to move through matches and Enter to insert an inline task chip. Escape closes the search. In a shared conversation, type @ to pick a colleague with access to the brand, including when you are a viewer. Private chats do not let you mention other people. Task and colleague chips stay in place inside your sent message. You can still ask the member by name in your text.

Select **Reply** on a message to quote it in your answer. You can cancel the reply before sending. Enter sends your message when the search is closed. Shift+Enter adds a line break. A message the member left unanswered shows **Ask the Writer**, or the member's name, on hover.

### Task fields

The [customer API](/api-keys) and its `list_actions` assistant tool include a `member` for each task. The Writer handles content and competitor gaps. The Publicist handles every outreach route and correction requests. The Engineer handles site fixes. Heralded's own daily updates, weekly reports, site checks, brand-mention checks and competitor searches belong to the Herald. Setup and prompt tracking have no member. API fields and member identifiers keep their existing names, including `analyst` and `analyst_week`.

`placed_position` is the task's position in the brand's proposed order, with 1 first. It is null for tasks nobody placed and clears when the task leaves Proposed. Proposed tasks come in this shared order, followed by tasks Heralded ranks.

Task timestamps describe separate moments:

* `started_at` is the first time Heralded starts the task. Revisions and retries keep that first start.
* `delivered_at` is when the result goes live, is sent or is published.
* `paid_off_at` is when verification credits a positive measured gain. Delivery alone does not prove a gain.

Dismissed tasks have none of these timestamps. Missing evidence leaves a timestamp null. Setup and prompt tracking do not count as team tasks and have no lifecycle timestamps.

While a task waits on you, `preview` carries up to 400 characters from the draft's opening lines, an email's recipient and subject, or the planned change. A preview is plain text and can include markup. Open the task to review the full result.

Each action also includes a `note` with what's happening, why it matters, what Heralded can do, what you need to do next and how the result is checked. Its `short_form` gives the proposal's reason. The written parts refresh when the evidence changes. Figures come from the action's facts, and an invalid generated note uses a template. `what_i_need_from_you` asks you to start a proposal or take the current review or approval step. It says there's nothing to do yet while Heralded works or waits for a result. What Heralded can do reflects your current site connection.

An action's `evidence` lists its linked prompts, the answers that name you and the total answers in the latest report, including daily answers pooled into it. Failed calls do not count. Each prompt has an Answers link, and the action has one link to the combined answers. A prompt with no answers has zero counts. Work with no linked prompts has an empty list and no combined link.

[`GET /v1/actions/{action_id}`](/api-reference/v1/get-action) and MCP `get_action` add what the task's pane shows: its state, the verbs it offers, its job and costs, expected and verified impact, `demand`, schedule, assignee, steps, current step and shared thread events. The verb the app calls **Start** is `dispatch` in the API. `drafts` lists the short-draft versions, `current_draft_version` names the one the task shows and `recipient` who an outreach draft greets. `application` adds the planned change's state, the value it was planned against and its `effect`. `insight_links` lists the weekly reports that raised or reprioritised the task. `content_piece` carries a long-form piece's stage and current full draft. `as_of` pins the evidence to a weekly report; the task itself is always current. These reads exclude per-person read markers and unread state.

[`GET /v1/brands/{brand_id}/work`](/api-reference/v1/get-work) and MCP `get_work` serve current agent jobs, the next scan, completed work in the last seven days and since the brand started, and the Herald's week. Each job names the task `get_action` reads in `action_id` and `action_kind`, who holds it in `holder`, a running scan's `progress` and its `current_step`. Answer and page tallies match Home's **Team activity**, including daily updates. The Herald's week counts actions proposed in the past seven days. It matches the Actions team, except `competitors_watched`, which counts the competitors a **Brand-mention check** looked at in the last seven days where the Actions card counts the competitors the brand tracks. The Board's filed count shows current open work.

## Moving work along

Where Heralded can do the work itself, the main button names the job, such as **Apply the fix**, **Draft the email** or **Write the piece**. Elsewhere, **I'll do it** takes it on yourself. You can also **Schedule** an action for later or **Dismiss** it.

Open a task to read its note and evidence. The pane names the team member and keeps its title and close button visible while you scroll. The status shows under the title. Below it, a task Heralded can start shows its [Autonomy](/concepts/autonomy) mode, which opens that setting. Under the **Ask first** preset the chip reads **Needs your OK**, and under any other preset it names the preset. **Owner** names who holds the task, or **You** until someone else takes it, and offers the people who can take it. It shows when you can assign the task and someone can take it. Primary controls sit in the bar at the pane's foot. A proposal offers **Not now** to dismiss it and **Start** to begin there. On Core, once the week's tasks are used, the button names the Monday it schedules the task for, such as **Start 12 Oct**. A short draft offers **Approve draft** and **Request changes**. A planned site write offers **Approve and apply** or **Apply the fix**. A long draft offers **Review** to open its review overlay. Opening a review applies no change.

The note has five parts: **What's happening**, **Why it matters**, **What I'll do**, **What I need from you** and **How we'll know**. The team member who holds the task speaks the note, so “I” is that member and “we” is the whole team. **What's happening** states the finding behind the task in up to two sentences. **What I'll do** holds the plan. Its request reflects the task's current step. Each label sits beside its text, or above it on a narrow screen, and **What I need from you** is highlighted. Once a task has started, the note folds to one line, its **What's happening** text, and the steps lead the pane, ahead of the evidence. Each step names who does it: the team member who holds the task, the Herald for the check afterwards, or the task's owner. Select the line to read the whole note. Evidence lists each linked prompt with the number of answers naming you and the total answers. Choose a prompt to read its answers, or the combined answer link below the prompts. A prompt with no answers still appears with zero counts.

To request a redraft, enter what should change and press the round **›** button at the right end of the field. The line below tells you how many free redrafts remain.

Other task controls, including **Schedule** and **I'll do it** when available, are in the **⋯** at the bottom-left of the pane. Review overlays keep approval at the bottom-right. The request-change field stays with the draft, along with **Edit**, **Save draft** and the editor's **Cancel**. A short message confirms each saved change or explains a failure, with **Undo** for changes that can be reversed. If you opened the task from another pane, its back control returns there.

If the Actions page cannot refresh an open task, the pane keeps the last loaded task and its address. The page shows an error until the next successful refresh or reopen.

When work lands in **Your turn**, such as a draft to approve, a content brief or draft to review, or a fix to confirm, Heralded sends one "Waiting on you" email that day. It goes to the task's owner, and to members who can start work and keep **Needs your approval** on in **Notifications**. A draft you asked for reaches the task's owner alone. Viewers don't get it.

Heralded drafts what it can. Nothing goes live on your site or leaves Heralded without your approval. You approve or edit each draft, or turn on an [Autonomy](/concepts/autonomy) switch that approves a kind of work in advance.

A site fix needs a [connection](/concepts/connections) for Heralded to apply it. With the WordPress Connector, it can apply robots.txt rules for AI crawlers and your homepage's structured data. Without one, Heralded drafts the change and you apply it. For your homepage's structured data, the draft is a snippet with a **Copy** button, which you send to your web developer.

## Outreach

Heralded picks one way to reach each cited site, from what kind of site it is and how its company relates to yours:

| Route | What Heralded prepares |
| - | - |
| Get cited | an email pitch to an editor or author, asking them to include you |
| Get listed | a checklist to claim your profile and gather reviews on a review site or directory |
| Propose co-marketing | an email to a company you marked as a partner |
| Join the conversation | a thread on a forum or social platform, with a suggested reply |

Heralded suggests a site only when AI engines cited it in at least two answers and Heralded read a page they cited. It leaves out a company that sells in your category, which includes a vendor whose cited pages name your competitors. It also leaves out app stores, marketplaces, news wires, press-release services, preprint servers and a site it could not classify. Review directories such as G2 and Capterra stay as **Get listed**.

Heralded ranks sites that leave your brand out by the search demand of the prompts they are cited on, weighted by each site's domain authority. When a weekly report no longer meets these rules, Heralded marks those suggestions **Not in the latest weekly report**. Work you have started stays.

Heralded never sends an email or posts for you. It drafts, and you send.

## Done and verified

When a daily update or weekly report no longer finds an issue you worked on, the task waits in **Your turn** for **Confirm fix** or **Not fixed**.

Delivered tasks land in **Done** when the result goes live, is sent or is published. Heralded then checks whether the work paid off. Until it is measured, a row can show its expected gain as an estimate, such as **+3 score points (est.)**. Once it is measured, the row shows the measured gain, such as **+3 pts Mentioned**. A site fix settles as **Fix is live** or **Not live**. Work aimed at prompts settles as verified, no move in the window, or inconclusive with the reason. [Verifying actions](/methodology/verifying-actions) explains the tests and the time each kind of work takes. Home's **Paying off** panel counts the work that verified.

If you marked a task done by mistake, **Reopen** returns it to **Your turn** until you mark it done again. Its earlier delivery stays in the thread. A failed site write returns to **Your turn**, even if the site took the write but still serves the old value.

Setup items finish as **Done** when their setting or connection is in place. They have no measured outcome.

When a task is delivered, workspace members whose role can see brand data get a "Done" email naming the task, and a "Measured" email when a report measures it. Billing members don't get them, and **Notifications** has no setting for them. A paused brand, a brand being deleted, or a workspace whose subscription has ended gets none of the task emails.

## Content Studio

Content Studio writes SEO and GEO pieces for you, meaning pieces written to rank in search and to be cited by AI engines. Heralded writes each brief from the pages AI already cites in your category. You approve the draft, then publish it on your site yourself. Heralded does not publish pieces, on WordPress or anywhere else. Under **Ask first**, the default, you approve the brief too.

Each piece has its own page under **Actions** with its brief, the writer's questions, the draft with its comments and versions, approval and publishing. A task's **Review** or **Answer the brief** opens it, and so do **Write this** and a piece's stage in [Content](/concepts/content#topics). A piece whose order is still being placed opens once the order goes through, and the page follows the piece as Heralded writes it, without a reload.

The piece's stage decides who holds the task. Questions, brief approval and draft review wait on you. Writing and checking remain Heralded's work. A piece waiting for your decision does not appear as drafting.

Once you approve a version, **Publish** offers **Copy HTML**, **Copy Markdown**, **Download .md** and **Download .html** to take the words to your site. Enter the page's address under **Live at** and **Save**. Saving delivers the piece and starts watching the page for citations.

When Heralded first finds an AI engine citing the page, the task timeline records its first citation once and names the engine.

Each piece costs one [content credit](/concepts/usage#content-credits), and each further round of rewrites you ask for costs another. Short drafts, such as a title and description, an outreach email or a review reply, cost nothing.

After you save an edit of a draft, the writer checks the new version and applies the fixes it is sure of itself, as its own version that lists them beside **Undo**. You review what is left: the findings that need your decision. When a step of its review could not run, the draft says which one, and you can still review and approve it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.