---
title: "List automations"
method: POST
path: "/automations/list"
tags: ["Automations"]
---

# List automations

`POST /automations/list`

Your automations with performance and outreach metrics. Includes creators reached, sample requests, videos posted, and GMV. reply_rate is populated for Running, Stopped, and Completed automations.

## Request body

- AutomationsListRequest — POST /automations/list request body. When ``start_date`` and/or ``end_date`` is supplied: 1. The ``creators_reached``, ``skipped``, and ``total_creators`` fields on every returned automation row are computed as DISTINCT creators reached/skipped WITHIN the requested window — not the lifetime aggregates that the unfiltered call returns. 2. The response includes a top-level ``aggregate`` object with shop-wide windowed totals sourced from ``customers.agency_dashboard_table`` — the same daily rollup the portal Outreach Metrics dashboard reads. Use ``aggregate.creators_reached`` / ``aggregate.tc_invites_creator_count`` etc. when you want numbers that match the portal UI exactly; the per-row fields are scoped per-automation and their sums won't equal the dashboard headlines. See CORE-4861 for the history of why the API and UI used to disagree on these numbers.
  - `page` integer
  - `page_size` integer
  - `sort_by` 'gmv' | 'created_at' | 'completed_at' | 'creators_reached' | 'dm_response_count', nullable
  - `sort_dir` 'asc' | 'desc'
  - `start_date` string, date, nullable — Inclusive window start (YYYY-MM-DD). Scopes ACTIVITY, not creation: when supplied (alone or with ``end_date``) the row set is restricted to automations that sent outreach in the window (an initial DM or a Target Collab invite dated inside it), so a long-running automation created earlier still appears with its in-window throughput. ``creators_reached`` / ``skipped`` / ``total_creators`` likewise switch from LIFETIME materialized-view values to in-window DISTINCT counts against the raw event tables. ``created_at`` is used only for sorting.
  - `end_date` string, date, nullable — Inclusive window end (YYYY-MM-DD). When supplied (alone or with ``start_date``), see ``start_date`` for the activity-window and creator-metric semantics.
  - `automation_type` string, nullable — Filter by the raw `Automation.automation_type` value, matched EXACTLY (case-sensitive). These values are historical/unnormalized — known examples: `Target Collab`, `TC Cleanup`, `New Sample Request Processing`. Unknown values (including the lowercase `target_collab` / `tc_cleanup` forms) match nothing. `Email` also returns nothing — email automations live in a separate table with no list read path yet; see the `excluded` block and POST /automations/email.
  - `status` string, nullable — Filter by status. Accepts either the display status (`Completed` | `Stopped` | `Running` | …) or the raw internal status (`continue` | `failed` | `inactive` | …) that /automations/stats reports. Evergreen CRM-group automations display as `Completed` between cycles — read the `is_evergreen` field on each row to tell 'armed and waiting' from 'finished'.
  - `show_archived` boolean — Include archived automations (state=archived). Default false mirrors the portal; the `excluded` block reports how many archived rows are hidden while this is false.
  - `created_via` string[], nullable — Include only automations created by these surfaces. Common values: `portal` | `api` | `api_direct` | `mcp` | `agent` | `slack` | `internal` | `campaign_tc_auto` (set is not closed). NULL/empty provenance matches `portal`. Values not present in the shop's automation data match nothing; future/internal values remain filterable when they appear in the data. Example: `["api_direct"]` returns only single-creator direct invites.
  - `exclude_created_via` string[], nullable — Exclude automations created by these surfaces. Applied after `created_via`. Example: `["api_direct"]` hides the `API direct invite — {handle}` rows produced by `POST /public/v1/target-collabs` so the list shows only your managed automations.

## Response `200`

Successful Response

- AutomationsListPaginatedResponse
  - `data` AutomationListItem[], required
    - `automation_id` integer, required
    - `automation_name` string, nullable
    - `automation_type` string, nullable
    - `is_evergreen` boolean — True for evergreen CRM-group automations that re-run whenever new creators enter the group. Between cycles these display `status: Completed` with `completed_at: null` — is_evergreen=true means armed-and-waiting, NOT finished.
    - `status` string, nullable — Display status from map_automation_status()
    - `status_message` string, nullable
    - `gmv` number, nullable
    - `sample_requests` integer, nullable — DB: automation_metrics.sample_request (singular)
    - `accepted_requests` integer, nullable — DB: automation_metrics.accepted_request (singular)
    - `videos_posted` integer, nullable
    - `videos_converted` integer, nullable
    - `creators_reached` integer, nullable — **Per-automation** distinct creators reached by THIS automation. Lifetime when the request has no `start_date`/`end_date`; windowed when a date filter is supplied. For the **shop-wide** windowed total that matches the portal's Outreach Metrics dashboard, use the top-level ``aggregate.creators_reached`` field — it's a different number computed from the agency rollup table and won't equal the sum of these per-row values. For a TC Cleanup automation this is coalesced to ``target_collab_cleanup_creators_reached`` (its reach lands there, not in new-outreach counts) so it is correct for every type.
    - `target_collab_cleanup_creators_reached` integer, nullable — Creators reached by a TC Cleanup automation (edited/removed invitations, DB status EDITED_INVITATION). Cleanup automations carry their reach here, not in the new-outreach counts; ``creators_reached`` above is coalesced to this.
    - `dm_response_count` integer, nullable — DB: automation_metrics.dm_response_count — unique creators who replied to DMs (30-day rolling)
    - `reply_rate` number, nullable — Computed: (dm_response_count / creators_reached) * 100. Populated for Running, Stopped, and Completed automations. Null when creators_reached is 0.
    - `skipped` integer, nullable — **Per-automation** creators the worker evaluated but did NOT reach (handle unresolved, outreach-limit blocked, previously invited, below criteria, etc.). Sourced from the same stats view as ``creators_reached`` / ``total_creators``: that view only retains rows for automations with recent activity, so all three read **null (not 0)** for automations idle for more than ~a day — null means 'no stats row', not 'zero skips'. For the always-available, per-creator breakdown of WHO was skipped and WHY, call ``GET /public/v1/automations/{automation_id}/creators``.
    - `total_creators` integer, nullable — **Per-automation** creators processed (reached + skipped) — NOT the audience size. 0 until sending begins; see ``creators_remaining`` for the resolved audience. Note: this is a per-row number scoped to ONE automation. Summing across rows will exceed the portal's shop-wide 'Total Creators' headline because the dashboard counts distinct creators-per-day across the whole shop, then sums days. For that headline number, read ``aggregate.tc_invites_creator_count`` on the top-level response.
    - `creators_remaining` integer, nullable — Resolved audience still to be processed. This is what confirms the audience resolved (e.g. your uploaded/CRM-group creators). Populated right after the automation is started.
    - `created_at` string, nullable
    - `completed_at` string, nullable
    - `created_via` string, nullable — Surface that created this automation. Always populated: rows with NULL/empty `created_via` (predating migration 020) surface as `portal`. Common values: `portal` | `api` | `api_direct` | `mcp` | `agent` | `slack` | `internal` | `campaign_tc_auto` (and other internal surfaces may appear — the set is not closed; unknown values are returned verbatim and remain filterable). **`api_direct`** marks a single-creator Target Collab automation created by `POST /public/v1/target-collabs` (the direct-invite convenience surface) — these are named `API direct invite — {handle}`. Filter the list by `created_via` / `exclude_created_via` to include or hide them.
  - `currency` string, required
  - `pagination` unknown, required
  - `date_range` DateRange
    - `start_date` string, nullable
    - `end_date` string, nullable
  - `shops_queried` string[], nullable — Shop names included when querying multiple shops (x-shop-id: all or comma-separated).
  - `aggregate` AutomationsListAggregate — Shop-wide windowed metric totals matching the portal's Outreach Metrics dashboard. Sourced from ``customers.agency_dashboard_table`` (a daily pre-aggregated rollup) and SUMmed across the daily rows inside the requested window — same computation the portal UI does. SHOP-WIDE — NOT per-automation. Counted DISTINCT per day, then summed across days; a creator reached on Tue AND Wed counts twice. Populated only when ``start_date`` and/or ``end_date`` is supplied on the request (the aggregate is window-scoped by design). ``None`` on unfiltered calls. Mapping to the portal's "Outreach Metrics" card columns: - ``creators_reached`` → "Creators Reached" - ``tc_invites`` → "Target Collabs" - ``tc_invites_creator_count`` → "Total Creators" sub-label under Target Collabs
    - `creators_reached` integer, nullable — Shop-wide distinct creators reached, summed across daily rollups in the window. Matches the portal's 'Creators Reached' column. NOT a global distinct count — a creator reached on multiple days is counted on each.
    - `tc_invites` integer, nullable — Shop-wide count of Target Collab invitations sent, summed across daily rollups in the window. Matches the portal's 'Target Collabs' column.
    - `tc_invites_creator_count` integer, nullable — Shop-wide distinct creators in Target Collab creator-list arrays, computed per day and summed across the window. Matches the portal dashboard's 'Total Creators' sub-label under Target Collabs — this is the field that customers comparing API to UI most commonly expect.
    - `creators_messaged` integer, nullable
    - `emails_sent` integer, nullable
    - `sample_request` integer, nullable
    - `sample_approved` integer, nullable
    - `videos_posted` integer, nullable
    - `videos_converted` integer, nullable
    - `spark_codes` integer, nullable
    - `added_showcase_affiliates` integer, nullable
    - `accepted_tc_count` integer, nullable
    - `tc_showcase_creator_count` integer, nullable
    - `tc_content_creator_count` integer, nullable
    - `tc_acceptance_rate` number, nullable — Average TC acceptance rate across the daily rollups in the window (mean of daily rates, not creator-weighted). Mirrors the portal dashboard's computation.
  - `excluded` object, nullable — Present only when this endpoint hides automations that exist for the shop, so 'none shown' can be told apart from 'none exist'. ``pagination.total_count`` counts only rows THIS endpoint returns (live, non-email). Keys: ``archived`` (count hidden unless ``show_archived=true``); ``email`` (count of email automations — a separate table managed via POST /automations/email, no list read path yet); and a ``note``.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/reacherapp/apis/reacher-data-api.md) · [All operations](https://skmtc.dev/reacherapp/apis/reacher-data-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/reacherapp/reacher-data-api/revisions/5eefff009b5b/schema)