Use this endpoint to retrieve signals for a specific account, contact, or time range. You can combine multiple query parameters to narrow results — for example, pulling every signal tied to a particular domain within a given week, or fetching all form_submit events from a single integration source.
Endpoint GET https://api.stairoids.com/v1/signals
Authentication Include your API key as a Bearer token in the Authorization header of every request.
Authorization : Bearer <api-key>
Query Parameters Filter signals by account domain. Returns only signals attributed to the account matching this domain, e.g. acme.com.
Filter signals by contact email. Returns only signals attributed to the contact with this email address, e.g. alice@acme.com.
Filter by signal type. Returns only signals whose type field exactly matches this value, e.g. page_visit.
Filter by originating source. Returns only signals whose source field exactly matches this value, e.g. activecampaign.
ISO 8601 start of the date range (inclusive), e.g. 2024-06-01T00:00:00Z. Filters by occurred_at.
ISO 8601 end of the date range (inclusive), e.g. 2024-06-30T23:59:59Z. Filters by occurred_at.
Maximum number of signals to return per page. Defaults to 50. Maximum allowed value is 200.
Pagination cursor returned in the previous response as meta.next_cursor. Pass this value to retrieve the next page of results.
Combine account_domain with from and to to pull all signals for a given account within a specific week — ideal for building per-account activity reports or weekly digest automations.
Code Examples curl --request GET \ --url 'https://api.stairoids.com/v1/signals?account_domain=acme.com&type=page_visit&from=2024-06-01T00:00:00Z&to=2024-06-30T23:59:59Z&limit=50' \ --header 'Authorization: Bearer <api-key>'
Response A successful request returns HTTP 200 OK with a paginated list of signal objects inside the data array.
Signals are returned in reverse chronological order — newest first. Use the cursor parameter to page through results when meta.next_cursor is non-null.
Response Fields An array of signal objects matching your query filters. Show signal object properties
The unique signal identifier, e.g. sig_abc123.
The signal type, e.g. page_visit.
The account record associated with this signal. The unique identifier for the account record.
The root domain of the account, e.g. acme.com.
The display name of the account, e.g. Acme Corp.
The current aggregate score for this account across all signals.
The contact record associated with this signal, or null if none was provided. The unique identifier for the contact record.
The email address of the contact.
The current aggregate score for this contact across all signals.
The score contribution of this individual signal (0–100).
The originating source for this signal.
The custom key-value properties attached to this signal.
ISO 8601 timestamp at which the signal was recorded.
Pagination and request metadata. An opaque cursor string to pass as the cursor query parameter to retrieve the next page of results. Returns null when you have reached the last page.
The total number of signals matching your current filter criteria, across all pages.
A unique identifier for this API request, useful for support and debugging.
ISO 8601 timestamp of when the server processed the request.
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" }, { "id" : "sig_bcd234" , "type" : "page_visit" , "account" : { "id" : "acc_xyz789" , "domain" : "acme.com" , "name" : "Acme Corp" , "score" : 84 }, "contact" : null , "score" : 8 , "source" : "my-website" , "properties" : { "page" : "/features" , "duration_seconds" : 20 }, "created_at" : "2024-06-14T09:11:44Z" } ], "meta" : { "next_cursor" : "cur_gghhiijj" , "total" : 134 , "request_id" : "req_33eeff44gghh" , "timestamp" : "2024-06-30T08:00:00Z" } }
Error Responses 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" } }