Get a Signal by ID — GET /v1/signals/:id

Use this endpoint to fetch the full details of a single signal by its ID. This is useful when you need to inspect the exact score contribution, resolved account and contact records, or attached properties for a specific event — for example, when debugging a webhook payload or auditing a scoring anomaly.

Endpoint

GET https://api.stairoids.com/v1/signals/:id

Authentication

Include your API key as a Bearer token in the Authorization header of every request.

Authorization: Bearer <api-key>

Path Parameters

string

required

The unique identifier of the signal you want to retrieve, e.g. sig_abc123. You receive this ID in the response when you create a signal via POST /v1/signals.

Code Examples

curl --request GET \
  --url https://api.stairoids.com/v1/signals/sig_abc123 \
  --header 'Authorization: Bearer <api-key>'

Response

A successful request returns HTTP 200 OK with the full signal object.

Response Fields

data

object

The full signal object.

Hide data properties

data.id

string

The unique signal identifier, e.g. sig_abc123.

data.type

string

The signal type, e.g. page_visit, email_open, or form_submit.

data.account

object

The account record associated with this signal.

Show account properties

data.account.id

string

The unique identifier for the account record, e.g. acc_xyz789.

data.account.domain

string

The root domain of the account, e.g. acme.com.

data.account.name

string

The display name of the account, e.g. Acme Corp.

data.account.score

number

The current aggregate score for this account across all signals.

data.contact

object | null

The contact record associated with this signal. Returns null if no contact was provided when the signal was created.

Show contact properties

data.contact.id

string

The unique identifier for the contact record, e.g. con_def456.

data.contact.email

string

The email address of the contact, e.g. alice@acme.com.

data.contact.score

number

The current aggregate score for this contact across all signals.

data.score

number

The score contribution assigned to this signal, on a scale of 0–100. Score weights are configured in your workspace settings.

data.source

string

The name of the originating tool or system that created this signal.

data.properties

object

The custom key-value pairs attached to this signal at creation time.

data.created_at

string

ISO 8601 timestamp at which Stairoids recorded this signal.

Example Response

{
  "data": {
    "id": "sig_abc123",
    "type": "page_visit",
    "account": {
      "id": "acc_xyz789",
      "domain": "acme.com",
      "name": "Acme Corp",
      "score": 84
    },
    "contact": {
      "id": "con_def456",
      "email": "alice@acme.com",
      "score": 42
    },
    "score": 12,
    "source": "my-website",
    "properties": {
      "page": "/pricing",
      "duration_seconds": 45
    },
    "created_at": "2024-06-15T14:23:01Z"
  },
  "meta": {
    "request_id": "req_55iijj66kkll",
    "timestamp": "2024-06-15T15:00:00Z"
  }
}

Error Responses

404 Not Found
401 Unauthorized

Returned when the signal ID does not exist in Stairoids, or when it belongs to a different workspace than the one associated with your API key.

{
  "error": {
    "code": "signal_not_found",
    "message": "No signal found with ID sig_abc123.",
    "request_id": "req_77mmnn88ooPP"
  }
}

Returned when the Authorization header is missing or your API key is invalid.

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key.",
    "request_id": "req_99qqrr00sstt"
  }
}

A 404 response does not distinguish between a signal that never existed and one that belongs to a different workspace. This is intentional — Stairoids does not leak signal IDs across workspace boundaries.

​Endpoint

​Authentication

​Path Parameters

​Code Examples

​Response

​Response Fields

​Example Response

​Error Responses

Endpoint

Authentication

Path Parameters

Code Examples

Response

Response Fields

Example Response

Error Responses