# Actions

Source: https://ceyo.ai/docs/signal/actions

### Actions

Retrieve prioritized recommendations, supporting findings, implementation guides, status, and measured outcomes.

**Scope:** Project

### List actions

`GET /projects/{project_id}/actions`

Returns actions for the selected project, with server-side filtering and pagination.

#### Path parameters

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `project_id` | project UUID \| project external ID | Required | Project identifier. |

#### Query parameters

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `q` | string | Optional | Search titles, descriptions, recommendations, and targets. |
| `status` | string | Optional; Default: active | active, todo, in\_progress, completed, dismissed, or resolved. active includes todo and in\_progress. |
| `priority` | string | Optional | low, medium, high, or critical. |
| `action_type` | string | Optional | Restrict results to one action type. |
| `effort_level` | low \| medium \| high | Optional | Restrict results by estimated effort. |
| `source_category` | string | Optional | Restrict results by work area. |
| `topic_id` | uuid | Optional | Return actions linked to one topic. |
| `page` | integer | Optional; Default: 1 | The 1-based page number. |
| `per_page` | integer | Optional; Default: 25 | Number of actions per page. Maximum: 100. |

#### Response envelope

`project_id`:**uuid**`actions`:**Action\[\]**`pagination`:**Pagination**

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `project_id` | uuid |  | Resolved Ceyo project identifier. |
| `actions` | Action\[\] |  | Actions matching the selected filters. |
| `pagination` | Pagination |  | Pagination metadata. |

#### Action

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `id` | uuid |  | Unique action identifier. |
| `status` | string |  | todo, in\_progress, completed, dismissed, or resolved. |
| `priority` | string |  | low, medium, high, or critical. |
| `estimated_impact` | integer |  | Relative expected impact from 0 to 100. |
| `effort_level` | low \| medium \| high |  | Estimated implementation effort. |
| `feasibility` | low \| medium \| high |  | Estimated ability to complete the recommendation. |
| `source_category` | string |  | owned, earned, reputation, local, competitive, operational, or general. |
| `content_format` | string \| null |  | Recommended deliverable format when relevant. |
| `action_type` | string |  | technical, content, visibility, competitor, listing, earned\_editorial, earned\_ugc, earned\_reference, sentiment\_correction, or general. |
| `title` | string |  | Short action title. |
| `description` | string \| null |  | Problem or opportunity addressed by the action. |
| `recommendation` | string \| null |  | Recommended outcome or approach. |
| `target_kind` | string |  | Type of resource targeted by the action. |
| `target` | string \| null |  | Target URL, prompt reference, profile, or scope value. |
| `guide` | Guide \| null |  | Structured implementation guide when available. |
| `topics` | TopicReference\[\] |  | Topics connected through supporting prompts and findings. |
| `started_at` | datetime \| null |  | When the action first entered in\_progress. |
| `completed_at` | datetime \| null |  | When the action was completed. |
| `dismissed_at` | datetime \| null |  | When the action was dismissed. |
| `resolved_at` | datetime \| null |  | When supporting findings were automatically resolved. |
| `created_at` | datetime |  | Action creation time. |
| `updated_at` | datetime |  | Last action update time. |

#### Guide

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `diagnosis` | string |  | Concise explanation of the diagnosed issue. |
| `gap_analysis` | string |  | Difference between the current and desired state. |
| `action_steps` | string\[\] |  | Ordered implementation steps. |
| `validation_steps` | string\[\] |  | Checks used to confirm completion. |
| `rollback_notes` | string |  | Recovery guidance when a change must be reverted. |
| `impact_prediction` | string |  | Expected outcome after implementation. |
| `impact_timeline_days` | integer |  | Estimated days before an outcome may become measurable. |

#### TopicReference

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `id` | uuid |  | Topic identifier. |
| `name` | string |  | Topic display name. |

#### Pagination

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `page` | integer |  | Current 1-based page. |
| `per_page` | integer |  | Number of records requested per page. |
| `total` | integer |  | Total records matching the request. |
| `total_pages` | integer |  | Total available pages. |

#### Request and response

```curl
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/actions?status=active&priority=high&page=1' \
  --header 'Authorization: Bearer ceyo_platform_...'
```

```json
{
  "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
  "actions": [
    {
      "id": "8ec60fe5-9c0b-41ea-98ce-9c98f846466f",
      "status": "in_progress",
      "priority": "high",
      "estimated_impact": 78,
      "effort_level": "medium",
      "feasibility": "high",
      "source_category": "owned",
      "content_format": "comparison_page",
      "action_type": "content",
      "title": "Create a focused comparison page",
      "description": "Competitors are cited for high-intent comparison prompts.",
      "recommendation": "Publish a factual comparison addressing the observed gaps.",
      "target_kind": "site",
      "target": "https://example.com",
      "topics": [
        {
          "id": "ab20526b-6bb2-436c-8c93-5bf77ea43848",
          "name": "AI visibility platforms"
        }
      ],
      "started_at": "2026-07-30T10:05:00Z",
      "completed_at": null,
      "dismissed_at": null,
      "resolved_at": null,
      "created_at": "2026-07-20T08:30:00Z",
      "updated_at": "2026-07-30T10:05:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 42,
    "total_pages": 2
  }
}
```

#### Errors

#### Error response envelope

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `error` | Error |  | Structured error payload. |

#### Error

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `code` | string |  | Stable snake\_case code suitable for programmatic handling. |
| `message` | string |  | Human-readable explanation of the failure. |
| `details` | object \| array \| null |  | Structured validation or request context when available. |
| `request_id` | string |  | Identifier to provide when requesting support. |

```json
{
  "error": {
    "code": "invalid_request",
    "message": "The request parameters are invalid.",
    "details": { "status": ["is not supported"] },
    "request_id": "req_01K1JQY1RQQ7N3C5H1K6J0P8AT"
  }
}
```

#### Status codes

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `400` | invalid\_request |  | A path value, query parameter, or JSON body is malformed. |
| `401` | invalid\_api\_key |  | The Bearer API key is absent or invalid. |
| `403` | forbidden |  | The API key cannot perform this operation. |
| `404` | not\_found |  | Project, location, or action was not found. |
| `429` | rate\_limit\_exceeded |  | Too many requests were made. |

### Get action

`GET /projects/{project_id}/actions/{action_id}`

Returns one action, its structured implementation guide, and all supporting findings in the selected project.

#### Path parameters

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `project_id` | project UUID \| project external ID | Required | Project identifier. |
| `action_id` | uuid | Required | Action identifier. |

#### Action response envelope

`project_id`:**uuid**`action`:**Action**`findings`:**Finding\[\]**

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `project_id` | uuid |  | Resolved Ceyo project identifier. |
| `action` | Action |  | Requested action and its implementation guide. |
| `findings` | Finding\[\] |  | Supporting findings linked to the action. |

#### Action

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `id` | uuid |  | Unique action identifier. |
| `status` | string |  | todo, in\_progress, completed, dismissed, or resolved. |
| `priority` | string |  | low, medium, high, or critical. |
| `estimated_impact` | integer |  | Relative expected impact from 0 to 100. |
| `effort_level` | low \| medium \| high |  | Estimated implementation effort. |
| `feasibility` | low \| medium \| high |  | Estimated ability to complete the recommendation. |
| `source_category` | string |  | owned, earned, reputation, local, competitive, operational, or general. |
| `content_format` | string \| null |  | Recommended deliverable format when relevant. |
| `action_type` | string |  | technical, content, visibility, competitor, listing, earned\_editorial, earned\_ugc, earned\_reference, sentiment\_correction, or general. |
| `title` | string |  | Short action title. |
| `description` | string \| null |  | Problem or opportunity addressed by the action. |
| `recommendation` | string \| null |  | Recommended outcome or approach. |
| `target_kind` | string |  | Type of resource targeted by the action. |
| `target` | string \| null |  | Target URL, prompt reference, profile, or scope value. |
| `guide` | Guide \| null |  | Structured implementation guide when available. |
| `topics` | TopicReference\[\] |  | Topics connected through supporting prompts and findings. |
| `started_at` | datetime \| null |  | When the action first entered in\_progress. |
| `completed_at` | datetime \| null |  | When the action was completed. |
| `dismissed_at` | datetime \| null |  | When the action was dismissed. |
| `resolved_at` | datetime \| null |  | When supporting findings were automatically resolved. |
| `created_at` | datetime |  | Action creation time. |
| `updated_at` | datetime |  | Last action update time. |

#### Guide

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `diagnosis` | string |  | Concise explanation of the diagnosed issue. |
| `gap_analysis` | string |  | Difference between the current and desired state. |
| `action_steps` | string\[\] |  | Ordered implementation steps. |
| `validation_steps` | string\[\] |  | Checks used to confirm completion. |
| `rollback_notes` | string |  | Recovery guidance when a change must be reverted. |
| `impact_prediction` | string |  | Expected outcome after implementation. |
| `impact_timeline_days` | integer |  | Estimated days before an outcome may become measurable. |

#### TopicReference

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `id` | uuid |  | Topic identifier. |
| `name` | string |  | Topic display name. |

#### Finding

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `source` | string |  | Analysis source that produced the finding. |
| `category` | string |  | Finding category. |
| `severity` | string |  | Finding severity. |
| `status` | string |  | Current finding lifecycle status. |
| `target_kind` | string |  | Type of resource that produced the signal. |
| `target` | string \| null |  | Target value when available. |
| `title` | string |  | Finding title. |
| `description` | string \| null |  | Evidence-backed finding description. |
| `recommendation` | string \| null |  | Recommended response to the finding. |
| `first_seen_at` | datetime |  | First detection time. |
| `last_seen_at` | datetime |  | Most recent detection time. |
| `resolved_at` | datetime \| null |  | Resolution time, when resolved. |

#### Request and response

```curl
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/actions/{action_id}' \
  --header 'Authorization: Bearer ceyo_platform_...'
```

```json
{
  "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
  "action": {
    "id": "8ec60fe5-9c0b-41ea-98ce-9c98f846466f",
    "status": "in_progress",
    "priority": "high",
    "estimated_impact": 78,
    "effort_level": "medium",
    "feasibility": "high",
    "source_category": "owned",
    "content_format": "comparison_page",
    "action_type": "content",
    "title": "Create a focused comparison page",
    "description": "Competitors are cited for high-intent comparison prompts.",
    "recommendation": "Publish a factual comparison addressing the observed gaps.",
    "target_kind": "site",
    "target": "https://example.com",
    "guide": {
      "diagnosis": "Competitors own the strongest comparison citations.",
      "gap_analysis": "The site does not answer the comparison intent directly.",
      "action_steps": [
        "Collect product evidence for each comparison criterion.",
        "Publish a transparent comparison page."
      ],
      "validation_steps": [
        "Confirm every claim has a source.",
        "Request indexing after publication."
      ],
      "rollback_notes": "Remove unsupported claims if evidence changes.",
      "impact_prediction": "Improved relevance for comparison prompts.",
      "impact_timeline_days": 30
    },
    "topics": [],
    "started_at": "2026-07-30T10:05:00Z",
    "completed_at": null,
    "dismissed_at": null,
    "resolved_at": null,
    "created_at": "2026-07-20T08:30:00Z",
    "updated_at": "2026-07-30T10:05:00Z"
  },
  "findings": [
    {
      "source": "visibility",
      "category": "citation_gap",
      "severity": "high",
      "status": "open",
      "target_kind": "site",
      "target": "example.com",
      "title": "Competitors own comparison citations",
      "description": "Competitor pages are repeatedly cited.",
      "recommendation": "Address the observed comparison intent.",
      "first_seen_at": "2026-07-10T07:30:00Z",
      "last_seen_at": "2026-07-30T09:30:00Z",
      "resolved_at": null
    }
  ]
}
```

#### Errors

#### Error response envelope

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `error` | Error |  | Structured error payload. |

#### Error

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `code` | string |  | Stable snake\_case code suitable for programmatic handling. |
| `message` | string |  | Human-readable explanation of the failure. |
| `details` | object \| array \| null |  | Structured validation or request context when available. |
| `request_id` | string |  | Identifier to provide when requesting support. |

```json
{
  "error": {
    "code": "invalid_request",
    "message": "The request parameters are invalid.",
    "details": { "status": ["is not supported"] },
    "request_id": "req_01K1JQY1RQQ7N3C5H1K6J0P8AT"
  }
}
```

#### Status codes

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `400` | invalid\_request |  | A path value, query parameter, or JSON body is malformed. |
| `401` | invalid\_api\_key |  | The Bearer API key is absent or invalid. |
| `403` | forbidden |  | The API key cannot perform this operation. |
| `404` | not\_found |  | Project, location, or action was not found. |
| `429` | rate\_limit\_exceeded |  | Too many requests were made. |

### Update action status

`PATCH /projects/{project_id}/actions/{action_id}`

Updates the customer-managed lifecycle status of an action. Resolved actions are controlled automatically by their supporting findings.

#### Path parameters

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `project_id` | project UUID \| project external ID | Required | Project identifier. |
| `action_id` | uuid | Required | Action identifier. |

#### Request body

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `status` | todo \| in\_progress \| completed \| dismissed |  | New customer-managed action status. |

#### Allowed transitions

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `todo` | → in\_progress, completed, dismissed |  | A new action can be started, completed, or dismissed. |
| `in_progress` | → todo, completed, dismissed |  | Work can be paused, completed, or dismissed. |
| `completed` | → todo |  | A completed action can be reopened. |
| `dismissed` | → todo |  | A dismissed action can be reopened. |

#### Action response envelope

`project_id`:**uuid**`action`:**Action**

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `project_id` | uuid |  | Resolved Ceyo project identifier. |
| `action` | Action |  | Updated action. |

#### Action

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `id` | uuid |  | Unique action identifier. |
| `status` | string |  | todo, in\_progress, completed, dismissed, or resolved. |
| `priority` | string |  | low, medium, high, or critical. |
| `estimated_impact` | integer |  | Relative expected impact from 0 to 100. |
| `effort_level` | low \| medium \| high |  | Estimated implementation effort. |
| `feasibility` | low \| medium \| high |  | Estimated ability to complete the recommendation. |
| `source_category` | string |  | owned, earned, reputation, local, competitive, operational, or general. |
| `content_format` | string \| null |  | Recommended deliverable format when relevant. |
| `action_type` | string |  | technical, content, visibility, competitor, listing, earned\_editorial, earned\_ugc, earned\_reference, sentiment\_correction, or general. |
| `title` | string |  | Short action title. |
| `description` | string \| null |  | Problem or opportunity addressed by the action. |
| `recommendation` | string \| null |  | Recommended outcome or approach. |
| `target_kind` | string |  | Type of resource targeted by the action. |
| `target` | string \| null |  | Target URL, prompt reference, profile, or scope value. |
| `guide` | Guide \| null |  | Structured implementation guide when available. |
| `topics` | TopicReference\[\] |  | Topics connected through supporting prompts and findings. |
| `started_at` | datetime \| null |  | When the action first entered in\_progress. |
| `completed_at` | datetime \| null |  | When the action was completed. |
| `dismissed_at` | datetime \| null |  | When the action was dismissed. |
| `resolved_at` | datetime \| null |  | When supporting findings were automatically resolved. |
| `created_at` | datetime |  | Action creation time. |
| `updated_at` | datetime |  | Last action update time. |

#### Guide

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `diagnosis` | string |  | Concise explanation of the diagnosed issue. |
| `gap_analysis` | string |  | Difference between the current and desired state. |
| `action_steps` | string\[\] |  | Ordered implementation steps. |
| `validation_steps` | string\[\] |  | Checks used to confirm completion. |
| `rollback_notes` | string |  | Recovery guidance when a change must be reverted. |
| `impact_prediction` | string |  | Expected outcome after implementation. |
| `impact_timeline_days` | integer |  | Estimated days before an outcome may become measurable. |

#### TopicReference

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `id` | uuid |  | Topic identifier. |
| `name` | string |  | Topic display name. |

#### Request and response

```curl
curl --request PATCH \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/actions/{action_id}' \
  --header 'Authorization: Bearer ceyo_platform_...' \
  --header 'Content-Type: application/json' \
  --data '{"status":"completed"}'
```

```json
{
  "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
  "action": {
    "id": "8ec60fe5-9c0b-41ea-98ce-9c98f846466f",
    "status": "completed",
    "completed_at": "2026-07-31T10:15:00Z",
    "updated_at": "2026-07-31T10:15:00Z"
  }
}
```

#### Errors

#### Error response envelope

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `error` | Error |  | Structured error payload. |

#### Error

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `code` | string |  | Stable snake\_case code suitable for programmatic handling. |
| `message` | string |  | Human-readable explanation of the failure. |
| `details` | object \| array \| null |  | Structured validation or request context when available. |
| `request_id` | string |  | Identifier to provide when requesting support. |

```json
{
  "error": {
    "code": "invalid_request",
    "message": "The request parameters are invalid.",
    "details": { "status": ["is not supported"] },
    "request_id": "req_01K1JQY1RQQ7N3C5H1K6J0P8AT"
  }
}
```

#### Status codes

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `400` | invalid\_request |  | A path value, query parameter, or JSON body is malformed. |
| `401` | invalid\_api\_key |  | The Bearer API key is absent or invalid. |
| `403` | forbidden |  | The API key cannot perform this operation. |
| `404` | not\_found |  | Project, location, or action was not found. |
| `409` | invalid\_transition |  | The requested status transition is not allowed. |
| `422` | invalid\_status |  | The submitted status is not writable. |
| `429` | rate\_limit\_exceeded |  | Too many requests were made. |

### Get action impact

`GET /projects/{project_id}/actions/impact`

Compares visibility signals before and after completed actions in the selected project. Actions remain pending until both baseline and comparison runs are available.

#### Path parameters

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `project_id` | project UUID \| project external ID | Required | Project identifier. |

#### Query parameters

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `start_on` | date | Optional; Default: 90 days before end\_on | First completion date to include. |
| `end_on` | date | Optional; Default: Today | Last completion date to include. |
| `topic_id` | uuid | Optional | Measure actions connected to one topic. |
| `action_type` | string | Optional | Measure one action type. |

#### Response envelope

`project_id`:**uuid**`period`:**ImpactPeriod**`summary`:**ImpactSummary**`timeline`:**ImpactTimelinePoint\[\]**`actions`:**ActionMeasurement\[\]**

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `project_id` | uuid |  | Resolved Ceyo project identifier. |
| `period` | ImpactPeriod |  | Resolved start\_on and end\_on. |
| `summary` | ImpactSummary |  | Completed, measured, pending, and outcome totals. |
| `timeline` | ImpactTimelinePoint\[\] |  | Weekly completion and visibility outcome series. |
| `actions` | ActionMeasurement\[\] |  | Measurements for up to 100 completed actions. |

#### ImpactPeriod

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `start_on` | date |  | First completion date included in the measurement window. |
| `end_on` | date |  | Last completion date included in the measurement window. |

#### ImpactSummary

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `completed_actions` | integer |  | Completed actions included in the measurement window. |
| `measured_actions` | integer |  | Actions with both baseline and comparison signals. |
| `pending_actions` | integer |  | Actions awaiting an eligible baseline or comparison signal. |
| `improved` | integer |  | Measured actions classified as improved. |
| `unchanged` | integer |  | Measured actions classified as unchanged. |
| `declined` | integer |  | Measured actions classified as declined. |
| `average_visibility_delta` | number \| null |  | Mean visibility percentage-point change, or null when no action is measured. |
| `average_citation_delta` | number \| null |  | Mean citation-count change, or null when no action is measured. |
| `average_sentiment_delta` | number \| null |  | Mean sentiment-score change, or null when no comparable values exist. |

#### ImpactTimelinePoint

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `date` | date |  | Start date of the represented week. |
| `completed` | integer |  | Actions completed during the represented week. |
| `measured` | integer |  | Completed actions with an available measurement. |
| `average_visibility_delta` | number \| null |  | Mean visibility percentage-point change, or null when the week has no measurements. |

#### ActionMeasurement

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `id` | uuid |  | Action identifier. |
| `title` | string |  | Action title. |
| `action_type` | string |  | Action type. |
| `completed_at` | datetime |  | Action completion time. |
| `topics` | TopicReference\[\] |  | Topics used to scope the measurement. |
| `status` | measured \| pending |  | Measurement availability. |
| `reason` | no\_baseline\_run \| awaiting\_post\_completion\_run \| null |  | Why a pending action cannot yet be measured. |
| `outcome` | improved \| unchanged \| declined \| null |  | Outcome derived from visibility change when measured. |
| `baseline_at` | datetime \| null |  | Baseline run completion time. |
| `comparison_at` | datetime \| null |  | Comparison run completion time. |
| `baseline` | ImpactSnapshot \| null |  | Signals immediately before completion when measured. |
| `comparison` | ImpactSnapshot \| null |  | Latest eligible signals after completion when measured. |
| `delta` | ActionMeasurementDelta \| null |  | Signal changes when the action is measured. |

#### ActionMeasurementDelta

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `visibility_percentage_points` | number \| null |  | Comparison visibility minus baseline visibility. |
| `citation_count` | integer \| null |  | Comparison citation count minus baseline citation count. |
| `sentiment_score` | number \| null |  | Comparison sentiment score minus baseline sentiment score. |
| `average_position` | number \| null |  | Improvement in average position; positive values indicate movement toward position one. |

#### ImpactSnapshot

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `visibility_percentage` | number |  | Primary brand visibility percentage. |
| `citation_count` | integer |  | Distinct cited pages. |
| `sentiment_score` | number \| null |  | Average primary-brand sentiment score. |
| `average_position` | number \| null |  | Average primary-brand position. |

#### TopicReference

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `id` | uuid |  | Topic identifier. |
| `name` | string |  | Topic display name. |

> **Outcome interpretation**
>
> Measurements show correlated before-and-after signals. They do not establish that an action was the only cause of a change.

#### Request and response

```curl
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/actions/impact?start_on=2026-05-01&end_on=2026-07-30' \
  --header 'Authorization: Bearer ceyo_platform_...'
```

```json
{
  "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
  "period": {
    "start_on": "2026-05-01",
    "end_on": "2026-07-30"
  },
  "summary": {
    "completed_actions": 12,
    "measured_actions": 9,
    "pending_actions": 3,
    "improved": 6,
    "unchanged": 2,
    "declined": 1,
    "average_visibility_delta": 4.8,
    "average_citation_delta": 3.2,
    "average_sentiment_delta": 0.4
  },
  "timeline": [
    {
      "date": "2026-07-27",
      "completed": 3,
      "measured": 2,
      "average_visibility_delta": 5.1
    }
  ],
  "actions": [
    {
      "id": "8ec60fe5-9c0b-41ea-98ce-9c98f846466f",
      "title": "Create a focused comparison page",
      "action_type": "content",
      "completed_at": "2026-07-10T10:15:00Z",
      "topics": [],
      "status": "measured",
      "outcome": "improved",
      "baseline_at": "2026-07-09T07:30:00Z",
      "comparison_at": "2026-07-30T09:30:00Z",
      "baseline": {
        "visibility_percentage": 35.0,
        "citation_count": 8,
        "sentiment_score": 6.8,
        "average_position": 3.4
      },
      "comparison": {
        "visibility_percentage": 42.5,
        "citation_count": 13,
        "sentiment_score": 7.3,
        "average_position": 2.8
      },
      "delta": {
        "visibility_percentage_points": 7.5,
        "citation_count": 5,
        "sentiment_score": 0.5,
        "average_position": 0.6
      }
    }
  ]
}
```

#### Errors

#### Error response envelope

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `error` | Error |  | Structured error payload. |

#### Error

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `code` | string |  | Stable snake\_case code suitable for programmatic handling. |
| `message` | string |  | Human-readable explanation of the failure. |
| `details` | object \| array \| null |  | Structured validation or request context when available. |
| `request_id` | string |  | Identifier to provide when requesting support. |

```json
{
  "error": {
    "code": "invalid_request",
    "message": "The request parameters are invalid.",
    "details": { "status": ["is not supported"] },
    "request_id": "req_01K1JQY1RQQ7N3C5H1K6J0P8AT"
  }
}
```

#### Status codes

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `400` | invalid\_request |  | A path value, query parameter, or JSON body is malformed. |
| `401` | invalid\_api\_key |  | The Bearer API key is absent or invalid. |
| `403` | forbidden |  | The API key cannot perform this operation. |
| `404` | not\_found |  | Project, location, or action was not found. |
| `429` | rate\_limit\_exceeded |  | Too many requests were made. |