Skip to main content
POST
Preview a radar
Send the same body you would send to create that radar, plus an optional limit, and get a few recent matches back right away. The body follows the create endpoint for its radar_type: Create Company Radar, Create Contact Radar or Create Industry Radar. Use it to tune your filters before you create the radar.
Previews are for checking your filters, not for collecting data. A preview can miss matches. Only company_new_hires can be previewed for now.

Results or no results

Both outcomes return 200. Check updates, not the message text:
  • Each update has the same content as a New Hires radar update.
  • “No matches returned” does not prove that no matches exist.
  • A preview is not saved as a radar. Its updates don’t appear in GET /v1/updates.

Request rules

  • An API key is required (x-api-key). Signed-in sessions are not accepted.
  • limit is optional: a whole number from 1 to 100, default 3. Keep it low (3–5). Higher limits are slower.
  • Don’t send updates_since. The preview picks its own search window, so matches usually come from recent months.
  • Filters (departments, seniorities, job_titles) follow the same rules as on create. See Filtering and personas.
  • webhook_url and custom_fields are checked as on create, then ignored. An existing radar for the same company doesn’t block a preview.
  • Other radar types return 400 “Preview not available”.

Pricing

  • Each returned update costs your per-update rate, shown in usage.unit_price_usd. Nothing returned is free.
  • Previews need an active account (not a trial) with per-update pricing for that radar type; otherwise you get 403.
  • One payment must cover limit × your rate before the preview starts; otherwise you get 402. Nothing is charged.
  • If you later create the radar, it may deliver (and bill) the same matches again.

Timing and pacing

  • Most previews answer in a few seconds. Set your client timeout to at least 35 seconds.
  • Send previews one after another, or a few at a time, rather than in bursts. Under heavy load, more previews come back with no matches.
  • A retry is a new preview and is charged for what it returns. In rare cases a 500 may still have been charged; GET /v1/account shows your current balance.

Dates

discovered_at is when we found the update: when it was stored, or the time of this preview for a fresh one. The hire’s own date is in content.start_date.

Authorizations

x-api-key
string
header
required

Body

application/json

The same body you would send to create that radar (Create Company, Contact or Industry Radar, by radar_type), plus an optional limit. Only company_new_hires can be previewed for now, so this schema shows the company fields. updates_since is not accepted. webhook_url and custom_fields are checked as on create, then ignored.

domain
string
required

The company's domain (e.g., stripe.com). Protocol, www, paths, and query parameters are automatically normalized, as on create.

Example:

"stripe.com"

radar_type
enum<string>
required

The radar type to preview. Only company_new_hires can be previewed for now; other types return 400 "Preview not available".

Available options:
company_new_hires
limit
integer
default:3

Most updates to return. Keep it low (3–5); higher limits are slower and each returned update is charged. Preview only — create endpoints reject limit.

Required range: 1 <= x <= 100
Example:

3

departments
string[]

Optional department filter, same values and rules as Create Company Radar.

Example:
seniorities
string[]

Optional seniority filter, same values and rules as Create Company Radar.

Example:
job_titles
string

Optional Boolean job-title expression, same syntax and rules as Create Company Radar. When present it takes precedence over departments and seniorities.

Example:

"\"Staff Engineer\" OR CTO"

profile_url
string<uri>

Optional LinkedIn company page URL, same rules as Create Company Radar (e.g., https://www.linkedin.com/company/stripe).

webhook_url
string<uri>

Accepted so you can send your create body unchanged. Checked as on create, then ignored.

custom_fields
object

Accepted so you can send your create body unchanged. Checked as on create, then ignored.

Response

Preview completed. updates holds what was found, newest first; an empty array means nothing was returned and nothing was charged. Check updates, not the message text.

status
enum<string>
required
Available options:
success
code
enum<integer>
required
Available options:
200
timestamp
string<date-time>
required
message
string
required

"Preview completed" when updates were returned, "Preview completed: no matches returned" when none were. Check updates, not the message text; no matches returned does not prove none exist.

preview_id
string<uuid>
required

Identifier for this preview, for support requests. Previews are not stored as radars and do not appear in GET /v1/updates.

updates
object[]
required

Up to limit updates, newest first. Empty when nothing was returned.

usage
object
required