--- title: "List Actions" method: POST path: "/actions/list" tags: ["Actions"] --- # List Actions `POST /actions/list` ## Request - Base URL: `https://api.peec.ai/customer/v1` - URL: `https://api.peec.ai/customer/v1/actions/list` - Auth: one of: - API key in header `X-API-Key` - API key in query parameter `api_key` - HTTP bearer The project's actions, the ones Peec generated and the ones the customer wrote themselves alike: what to do, on which page or site, and how much impact it is expected to have if it is done. `created_by` says which of the two an action is, and only a customer's own can be deleted or reshaped. Filters combine with AND, except `targets`, `groups`, `archetypes` and `platforms`, which combine with OR across the four. The action detail endpoint carries a single action's steps, brief, evidence and impacted prompts. ## Request body - object - `project_id` string: Required if using a company api key - `types` string[]: Defaults to every published type. `TEMPLATE_ACTION` is a per-platform playbook filled in for one page; `CONTENT_BRIEF` and `CATEGORY_SITUATION_BRIEF` are net-new content to write; `CONTRADICTIONS_EXTERNAL_SOURCES` requests correction of one third-party source page that conflicts with a verified brand fact; `CONTRADICTIONS_OWNED_SOURCES` corrects one source page on a domain the brand owns; `SEO_ISSUE` and `ROBOTS_TXT` are technical fixes to a site the brand controls; `PDP_OPTIMISATION` improves one product page; `MANUAL_ACTION` is work a customer described themselves that matches none of the other shapes; `CONTENT_OPTIMISATION` improves an existing page the brand owns, and appears only on projects with content optimisation enabled — the optimize content endpoint returns its article and suggestions. - `statuses` string[]: Defaults to every status. `PENDING` is a suggestion nobody has decided on, `PLANNED` is an action you wrote and have not started, `ACCEPTED` is in progress, `COMPLETED` is done, `REJECTED` was declined, `EXPIRED` was left untouched for 30 days and closed automatically. - `categories` string[]: The off-site playbook a template action follows (the upper-case values), or the audit check an `SEO_ISSUE` came from (the lower-case ones). `agent_readiness` is the AI agent readiness audit, which covers files written for AI agents such as llms.txt. A playbook is orthogonal to the group, so the same one appears across groups, and narrowing by both means the intersection. Content briefs and `ROBOTS_TXT` actions carry none and match nothing here. - `domains` string[]: The site an `SEO_ISSUE` was raised against. Every other type carries none and matches nothing here. - `topic_ids` string[]: Only actions on these topics (see the topics endpoint). - `model_channel_ids` string[]: Only actions affecting these AI engine channels (see the model channels endpoint). - `country_codes` string[]: ISO 3166-1 alpha-2 markets. An action carrying no markets is not scoped to one, so every selection matches it. - `targets` string[]: `owned` means the action lands on a page the brand controls; `earned` means a third-party page, which covers editorial coverage and community posts alike. A UGC action is `earned` even when the brand writes the post itself. - `groups` string[]: The kind of surface the action lands on. - `archetypes` string[]: The kind of page a content brief says to create. Template actions carry no archetype and match nothing here, so this narrows the answer to content briefs. - `platforms` string[]: Registrable domain of a third-party action. Own-site actions carry none and match nothing here. - `order_by` 'impact' | 'created_at': `impact` is the order the Actions page ranks by, strongest expected gain first. `created_at` reads newest first, which is how to find what Peec generated since the last read. - `direction` 'asc' | 'desc' - `limit` integer - `offset` integer ## Response `200` Success - object: Success - `data` object[], required - `id` string, uuid, required - `type` 'TEMPLATE_ACTION' | 'CONTENT_BRIEF' | 'CATEGORY_SITUATION_BRIEF' | 'CONTRADICTIONS_EXTERNAL_SOURCES' | 'CONTRADICTIONS_OWNED_SOURCES' | 'SEO_ISSUE' | 'ROBOTS_TXT' | 'PDP_OPTIMISATION' | 'MANUAL_ACTION' | 'CONTENT_OPTIMISATION', required - `status` 'PENDING' | 'PLANNED' | 'ACCEPTED' | 'REJECTED' | 'COMPLETED' | 'EXPIRED', required - `title` string, required - `group` 'OWNED' | 'EDITORIAL' | 'REFERENCE' | 'UGC' | 'OTHER', required - `category` string, nullable, required: The off-site playbook a template action follows, or the audit check an `SEO_ISSUE` came from — normally one of the values the `categories` filter accepts. Null on content briefs and `ROBOTS_TXT` actions. - `target` 'owned' | 'earned', required - `archetype` 'HOMEPAGE' | 'CATEGORY_PAGE' | 'PRODUCT_PAGE' | 'LISTICLE' | 'COMPARISON' | 'PROFILE' | 'ALTERNATIVE' | 'DISCUSSION' | 'HOW_TO_GUIDE' | 'ARTICLE' | 'REVIEW' | 'OTHER', nullable, required: The kind of page a content brief says to create. Null on template actions, and on content briefs generated before Peec recorded it. - `platform` string, nullable, required: Registrable domain of the third-party site. Null on own-site actions. - `topic_id` string, nullable, required - `source` string, required: The page the action targets. Not always a url: a content brief describes a page that does not exist yet and carries the sentinel `content-brief` (`situation-brief` on a `CATEGORY_SITUATION_BRIEF`), an `SEO_ISSUE` names the audit that raised it and puts its target in `domain`, and a `ROBOTS_TXT` action carries a bare hostname. - `domain` string, nullable, required: The site an `SEO_ISSUE` was raised against, which is what it applies to rather than a single page. Null on every other type. - `country_codes` string[], required: Markets the action is scoped to. Empty when it applies to every market the project tracks. - `model_channel_ids` string[], required - `impact` 'VERY_LOW' | 'LOW' | 'MEDIUM' | 'HIGH' | 'VERY_HIGH', required: How much the action is expected to gain if it is completed, banded against every action in the project, so it reads the same whatever the filters are. On an `SEO_ISSUE` the band comes from the issue's severity instead. This is the impact the app shows, and the only measure of expected gain the API publishes. - `step_count` number, required: How many steps the action has. - `completed_step_count` number, required - `created_at` string, required - `status_updated_at` string, nullable, required: When the status last changed. Null while still `PENDING`. On a `COMPLETED` action this is when the work was done, which the customer can backdate with `completed_at`. - `created_by` 'peec' | 'customer', required: Who wrote the action. Only a `customer` one can be deleted or have its `kind` changed; a `peec` one is declined through the status endpoint instead. - `priority` 'none' | 'low' | 'medium' | 'high', nullable, required: How much the customer says the action matters. It fills the same bars `impact` fills on a generated action, and is null on one nobody has set. - `assignee_user_id` string, nullable, required: The project member the work is on. Null when unassigned. - `due_on` string, nullable, required: Calendar day in the project's timezone. - `tag_ids` string[], required: Tags the customer filed the action under. - `total_count` number, required: Actions matching the filters, ignoring pagination. ## Changes - **2026-11-03** `9d774600c8eb`: 1 warning, 3 info - added the new `exa-0` enum value to the `data/items/model_channel_ids/items/` response property for the response status `200` - added the new `exa-0` enum value to the request property `model_channel_ids/items/` (media type: application/json) - added the new `exa-0` enum value to the request property `model_channel_ids/items/` (media type: application/x-www-form-urlencoded) - added the new `exa-0` enum value to the request property `model_channel_ids/items/` (media type: multipart/form-data) - **2026-11-03** `9fdffdff48a5`: 1 info - endpoint added [Operation history](https://skmtc.dev/peec/apis/peec-ai-customer-api/changes/actions/list/post.md) --- [API](https://skmtc.dev/peec/apis/peec-ai-customer-api.md) - [All operations](https://skmtc.dev/peec/apis/peec-ai-customer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/peec/apis/peec-ai-customer-api/revisions/9d774600c8eb?raw)