Signal API
Bulk operations as MarkdownUse a clean Markdown version of this page with an agent or local tooling.

Bulk operations

Poll asynchronous project and location creation and inspect the result of every submitted record.

GET
/bulk-operations/{id}

Returns the current state and item results for one bulk create operation.

Parameters

Path parameters

iduuid

Bulk operation identifier returned by a bulk create request.

Required
Response

BulkOperation response envelope

id:uuidtype:projects | locationsstatus:pending | running | completed | completed_with_errors | failedparent_project_id:uuid | nulltotal:integerpending:integersucceeded:integerfailed:integerstatus_url:stringitems:BulkOperationItem[]
iduuid

Bulk operation identifier.

typeprojects | locations

Resource type created by the operation.

statuspending | running | completed | completed_with_errors | failed

Current operation state.

parent_project_iduuid | null

Parent project for a location operation; null for a project operation.

totalinteger

Submitted record count.

pendinginteger

Records that have not reached a terminal state.

succeededinteger

Records created successfully.

failedinteger

Records that failed validation or processing.

status_urlstring

Relative URL for polling this operation.

itemsBulkOperationItem[]

One result for each submitted record, ordered by input index.

Object

BulkOperationItem

indexinteger

Zero-based position in the submitted array.

statuspending | queued | running | succeeded | failed

Current item state.

resource_iduuid

Created project or location identifier when successful.

external_idstring | null

Partner identifier copied from the created resource.

onboarding_startedboolean

Whether this item created an onboarding run from start: true.

onboarding_operationOnboardingOperation

Onboarding status and polling URL when onboarding_started is true.

errorobject

Stable error code, message, and field details for a failed item.

PollingPoll the returned status_url until the operation is completed, completed_with_errors, or failed. Item failures do not roll back successful records.
Safe errorsItem errors contain stable public codes and sanitized field details. Unexpected internal failures return processing_failed without provider names, exception messages, or implementation details.

Request and response

Example requestcURL
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/bulk-operations/f9bc15cc-e9c9-4e93-a93e-b713c92c7315' \
  --header 'Authorization: Bearer ceyo_platform_...'
Example responseJSON
{
  "bulk_operation": {
    "id": "f9bc15cc-e9c9-4e93-a93e-b713c92c7315",
    "type": "projects",
    "status": "completed_with_errors",
    "parent_project_id": null,
    "total": 2,
    "pending": 0,
    "succeeded": 1,
    "failed": 1,
    "created_at": "2026-08-04T15:00:00Z",
    "started_at": "2026-08-04T15:00:01Z",
    "completed_at": "2026-08-04T15:00:03Z",
    "status_url": "/v1/bulk-operations/f9bc15cc-e9c9-4e93-a93e-b713c92c7315",
    "items": [
      {
        "index": 0,
        "status": "succeeded",
        "resource_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
        "external_id": "partner-project-acme",
        "onboarding_started": true,
        "onboarding_operation": {
          "id": "1c07ea43-a8fe-4d07-8741-9c624d67b466",
          "status": "queued",
          "resource_type": "project",
          "resource_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
          "progress": {
            "completed": 0,
            "total": 6
          },
          "message": "Onboarding is queued.",
          "steps": [
            {
              "key": "enrichment",
              "status": "pending"
            },
            {
              "key": "topics",
              "status": "pending"
            },
            {
              "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"
        },
        "started_at": "2026-08-04T15:00:01Z",
        "completed_at": "2026-08-04T15:00:02Z"
      },
      {
        "index": 1,
        "status": "failed",
        "error": {
          "code": "validation_failed",
          "message": "The record failed validation.",
          "details": [
            {
              "field": "package_id",
              "message": "is invalid"
            }
          ]
        },
        "started_at": "2026-08-04T15:00:01Z",
        "completed_at": "2026-08-04T15:00:03Z"
      }
    ]
  }
}
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

401invalid_api_key

The API key is absent, invalid, expired, or revoked.

404bulk_operation_not_found

The operation does not exist or is outside the API key scope.