---
title: "Preview Signal"
method: POST
path: "/v1/signals/preview"
tags: ["signals"]
---

# Preview Signal

`POST /v1/signals/preview`

## Request

- Base URL: `https://api.topo.io`
- URL: `https://api.topo.io/v1/signals/preview`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/topo/apis/topo-public-api/docs/v1/signals/preview/post.ts> (a function with typed inputs; its response is checked against the schema)

Sample what a preset would detect, without creating a signal.

Returns up to 10 recent matches over a 30-day window. The sample is
wider than a live run: no audience filter and no dedup are applied, so
use it to check the detection filters, not to predict volume.

Requires the `signals:read` scope on the API key.

## Request body

- PreviewSignalPublicInput
  - `signal_type` 'LINKEDIN_OWN_POST_ENGAGEMENT' | 'LINKEDIN_COMPETITOR_POST_ENGAGEMENT' | 'LINKEDIN_PERSON_POST_ENGAGEMENT' | 'LINKEDIN_KEYWORD_MENTION' | 'LINKEDIN_OWN_COMPANY_FOLLOWERS' | 'LINKEDIN_COMPETITOR_FOLLOWERS' | 'LINKEDIN_COMPANY_PAGE_FOLLOWERS' | 'HIRING_SIGNALS' | 'JOB_DESCRIPTION_KEYWORD' | 'FUNDING_EVENTS' | 'TECH_ADOPTION' | 'NEWS_EVENTS' | 'NEW_JOB' | 'CUSTOM_EVENT' | 'LINKEDIN_PARTNER_FOLLOWERS' | 'LINKEDIN_CUSTOMER_FOLLOWERS' | 'LINKEDIN_PARTNER_POST_ENGAGEMENT' | 'LINKEDIN_CUSTOMER_POST_ENGAGEMENT' | 'LINKEDIN_COMPANY_PAGE_POST_ENGAGEMENT' | 'LINKEDIN_OWN_PROFILE_POST_ENGAGEMENT' | 'LINKEDIN_OWN_EMPLOYEES_POST_ENGAGEMENT' | 'LINKEDIN_COMPETITOR_EMPLOYEES_POST_ENGAGEMENT' | 'LINKEDIN_PARTNER_EMPLOYEES_POST_ENGAGEMENT' | 'LINKEDIN_CUSTOMER_EMPLOYEES_POST_ENGAGEMENT' | 'LINKEDIN_OWN_BRAND_MENTION' | 'LINKEDIN_COMPETITOR_MENTION' | 'LINKEDIN_PARTNER_MENTION' | 'LINKEDIN_CUSTOMER_MENTION' | 'LINKEDIN_EVENT_MENTION' | 'COMPETITOR_TECH_ADOPTION' | 'INTEGRATION_TECH_ADOPTION' | 'LINKEDIN_EVENT_PAGE_FOLLOWERS' | 'CHAMPION_CHANGED_JOB' | 'CRM_LIST_ENTRY', required
  - `search_filters` FilterTexts

## Response `200`

Successful Response

- SignalPreviewPublicOutput
  - `window_days` integer, required: How many days back the sample looked.
  - `total_count` integer, nullable, required: How many facts the source reports over the window, when it counts them.
  - `items` SignalPreviewEntryPublicOutput[], required: A sample of recent matches, newest first.
    - `event_type` 'CLIENT_POST_REACTION' | 'CLIENT_POST_COMMENT' | 'COMPETITOR_POST_REACTION' | 'COMPETITOR_POST_COMMENT' | 'PERSON_POST_REACTION' | 'CLIENT_PAGE_FOLLOW' | 'COMPETITOR_PAGE_FOLLOW' | 'COMPANY_PAGE_FOLLOW' | 'PUBLIC_BRAND_MENTION_LINKEDIN' | 'PAIN_POINT_PUBLIC_POST' | 'LEADERSHIP_HIRING' | 'HIRING_SURGE' | 'NEW_ROLE' | 'TECH_ADOPTED' | 'TECH_DROPPED' | 'FUNDING_EVENT' | 'M_AND_A_EVENT' | 'LEADERSHIP_CHANGE_NEWS' | 'BRAND_MENTION_NEWS' | 'CUSTOM_EVENT', required
    - `company_name` string, nullable: Name of the detected company.
    - `company_domain` string, nullable: Domain of the detected company.
    - `first_name` string, nullable: First name of the detected person.
    - `last_name` string, nullable: Last name of the detected person.
    - `job_title` string, nullable: Job title of the detected person.
    - `linkedin_url` string, nullable: LinkedIn URL of the detected person.
    - `email` string, nullable: Email of the detected person.
  - `unavailable_reason` string, nullable: Why this preset returned no sample. Empty when a sample was attempted.

## Changes

- **2026-10-08** `16f692efb3db`: 1 info
  - added the optional property `unavailable_reason` to the response with the `200` status
- **2026-09-30** `451748979321`: 1 info
  - added the new `linkedin_watched_engagement` enum value to the request property `search_filters/propertyNames/`
- **2026-09-18** `5906bed561be`: 1 info
  - added the new `tech_min_confidence` enum value to the request property `search_filters/propertyNames/`
- **2026-09-11** `242d6cb1e182`: 2 breaking
  - removed the enum value `has_business_email` of the request property `search_filters/propertyNames/`
  - removed the enum value `has_email` of the request property `search_filters/propertyNames/`
- **2026-09-09** `d037d17aecd4`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/topo/apis/topo-public-api/changes/v1/signals/preview/post.md)

---

[API](https://skmtc.dev/topo/apis/topo-public-api.md) - [All operations](https://skmtc.dev/topo/apis/topo-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/topo/apis/topo-public-api/revisions/1eb3139a398e?raw)