# Onboarding operations

Source: https://ceyo.ai/docs/signal/onboarding-operations

### Onboarding operations

Poll automatic project and location onboarding with one shared operation endpoint.

### Get onboarding operation

`GET /onboarding-operations/{id}`

Returns safe progress for one project or location onboarding operation.

#### Path parameters

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `id` | uuid | Required | Onboarding operation identifier returned when a project or location is created with start: true. |

#### OnboardingOperation response envelope

`id`:**uuid**`status`:**queued | running | waiting\_visibility | waiting\_diagnosis | succeeded | partial | failed | cancelled**`resource_type`:**project | location**`resource_id`:**uuid**`current_step`:**string | null**`progress`:**object**`message`:**string**`error`:**object | null**`steps`:**OnboardingStep\[\]**`status_url`:**string**

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `id` | uuid |  | Onboarding operation identifier. |
| `status` | queued \| running \| waiting\_visibility \| waiting\_diagnosis \| succeeded \| partial \| failed \| cancelled |  | Current operation state. |
| `resource_type` | project \| location |  | Resource being onboarded. |
| `resource_id` | uuid |  | Project or location identifier. |
| `current_step` | string \| null |  | Current onboarding step, or null before work begins. |
| `progress` | object |  | Completed and total step counts. |
| `message` | string |  | Stable, customer-safe status message. |
| `error` | object \| null |  | Stable public error code and message for failed or partial operations. |
| `steps` | OnboardingStep\[\] |  | Public status for each onboarding step. |
| `status_url` | string |  | Relative URL for polling this operation. |

> **Polling**
>
> Poll `status_url` until the status is `succeeded`, `partial`, `failed`, or `cancelled`.

> **Safe errors**
>
> Status and step errors use fixed public codes and messages. Provider names, exception text, and internal metadata are never returned.

#### Request and response

```curl
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/onboarding-operations/1c07ea43-a8fe-4d07-8741-9c624d67b466' \
  --header 'Authorization: Bearer ceyo_platform_...'
```

```json
{
  "onboarding_operation": {
    "id": "1c07ea43-a8fe-4d07-8741-9c624d67b466",
    "status": "running",
    "resource_type": "location",
    "resource_id": "a1308d14-149c-4dd7-a4c5-295ac9090f58",
    "current_step": "topics",
    "progress": {
      "completed": 1,
      "total": 6
    },
    "message": "Onboarding is in progress.",
    "steps": [
      {
        "key": "enrichment",
        "status": "succeeded"
      },
      {
        "key": "topics",
        "status": "running"
      },
      {
        "key": "prompts",
        "status": "pending"
      },
      {
        "key": "competitors",
        "status": "pending"
      },
      {
        "key": "visibility",
        "status": "pending"
      },
      {
        "key": "diagnosis",
        "status": "pending"
      }
    ],
    "status_url": "/v1/onboarding-operations/1c07ea43-a8fe-4d07-8741-9c624d67b466",
    "created_at": "2026-08-04T15:00:00Z",
    "started_at": "2026-08-04T15:00:01Z",
    "updated_at": "2026-08-04T15:00:03Z"
  }
}
```

#### 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": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
```

#### Status codes

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `400` | invalid\_request |  | The operation ID is not a UUID. |
| `401` | invalid\_api\_key |  | The API key is absent, invalid, expired, or revoked. |
| `403` | forbidden |  | The API key lacks read or write access for the resource being onboarded. |
| `404` | not\_found |  | The operation does not exist or is outside the API key scope. |