> ## Documentation Index > Fetch the complete documentation index at: https://docs.tamradar.com/llms.txt > Use this file to discover all available pages before exploring further. # Preview Radar > See a few recent matches for a radar's filters before you create it. 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](https://docs.tamradar.com/api-reference/create-company-radar.md), [Create Contact Radar](https://docs.tamradar.com/api-reference/create-contact-radar.md) or [Create Industry Radar](https://docs.tamradar.com/api-reference/create-industry-radar.md). Use it to tune your filters before you create the radar. > [!NOTE] > > Previews are for checking your filters, not for collecting data. A preview can > miss matches. Only `company_new_hires` can be previewed for now. ```bash theme={null} curl -X POST "https://api.tamradar.com/v1/radars/preview" \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"domain": "stripe.com", "radar_type": "company_new_hires", "departments": ["Engineering"], "seniorities": ["Director"], "limit": 3}' ``` ## Results or no results Both outcomes return `200`. Check `updates`, not the message text: ```javascript theme={null} if (response.updates.length > 0) { // Charged: updates.length × usage.unit_price_usd, shown in usage.consumed_usd } else { // Nothing returned: free. Retrying costs nothing. } ``` * Each update has the same `content` as a [New Hires](https://docs.tamradar.com/webhooks/company/new-hires.md) 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](https://docs.tamradar.com/guides/filtering-and-personas.md). * `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`. ## OpenAPI ````yaml api_specs.yaml POST /v1/radars/preview openapi: 3.0.0 info: title: TAMradar API version: '1.0' description: Canonical OpenAPI spec for TAMradar customer-facing APIs. servers: - url: https://api.tamradar.com description: Production API server security: [] paths: /v1/radars/preview: post: tags: - Radars summary: Preview a radar description: >- Runs a small, one-off search with the same body you would send to create a radar, and returns a few recent matches right away. Use it to check your filters before you create the radar. Previews are for checking filters, not for collecting data: a preview can miss matches. Only `company_new_hires` can be previewed for now. Each returned update is charged at your per-update rate (`usage.unit_price_usd`); a preview that returns nothing is free. Requests count toward your account's write rate limit. Send previews one after another rather than in bursts. operationId: previewRadar requestBody: required: true description: >- 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. content: application/json: schema: $ref: '#/components/schemas/RadarPreviewRequest' example: domain: stripe.com radar_type: company_new_hires departments: - Engineering seniorities: - Director limit: 3 responses: '200': description: >- 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. content: application/json: schema: $ref: '#/components/schemas/RadarPreviewResponse' examples: match: summary: Updates returned (charged per update) value: status: success code: 200 timestamp: '2026-10-29T10:00:00Z' message: Preview completed preview_id: 6f1c2b7e-1a3d-4c5e-9f00-2b3c4d5e6f70 updates: - update_type: preview_finding discovered_at: '2026-10-29T10:00:00Z' data: radar_type: company_new_hires domain: stripe.com content: full_name: Jane Doe first_name: Jane last_name: Doe profile_url: https://www.linkedin.com/in/jane-doe title: Director of Engineering start_date: '2026-09-01' country: United States departments: - Engineering seniority: Director usage: unit_price_usd: 0.14 consumed_usd: 0.14 balance_remaining_usd: 124.86 no_match: summary: Nothing returned (free) value: status: success code: 200 timestamp: '2026-10-29T10:00:00Z' message: 'Preview completed: no matches returned' preview_id: 2f0c7a9e-61b4-4c0e-9a51-3c1f0d7b8e21 updates: [] usage: unit_price_usd: 0.14 consumed_usd: 0 balance_remaining_usd: 124.86 '400': description: >- Invalid request — not charged. The radar type can't be previewed, a field is invalid, `updates_since` was sent, or the JSON is malformed. Field errors come back together, one entry per field. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: type_not_available: summary: Radar type can't be previewed value: status: error code: 400 message: Preview not available errors: - field: radar_type reason: >- Previews are not available for company_job_openings. Supported: company_new_hires. For this type, create the radar instead. timestamp: '2026-10-29T10:00:00Z' error_id: 2f0c7a9e-61b4-4c0e-9a51-3c1f0d7b8e21 invalid_limit: summary: Invalid limit value: status: error code: 400 message: Invalid request body errors: - field: limit reason: limit must be a whole number from 1 to 100 (default 3) timestamp: '2026-10-29T10:00:00Z' error_id: 2f0c7a9e-61b4-4c0e-9a51-3c1f0d7b8e21 updates_since_sent: summary: updates_since is not accepted value: status: error code: 400 message: Invalid request body errors: - field: updates_since reason: >- previews choose their own search window; set updates_since when you create the radar timestamp: '2026-10-29T10:00:00Z' error_id: 2f0c7a9e-61b4-4c0e-9a51-3c1f0d7b8e21 invalid_filters: summary: Invalid filter value value: status: error code: 400 message: Invalid filters errors: - field: departments reason: >- Invalid department(s): Galactic. Valid values: Accounting, Administrative, Business Development, … timestamp: '2026-10-29T10:00:00Z' error_id: 2f0c7a9e-61b4-4c0e-9a51-3c1f0d7b8e21 '401': description: >- Missing, invalid or inactive API key — not charged. Previews need an API key; signed-in sessions are not accepted. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: status: error code: 401 message: Missing API key errors: - field: x-api-key reason: API key is required timestamp: '2026-10-29T10:00:00Z' error_id: 2f0c7a9e-61b4-4c0e-9a51-3c1f0d7b8e21 '402': description: >- Not enough balance — not charged. One payment must cover `limit` × your per-update rate before the preview starts. Top up or lower `limit`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: status: error code: 402 message: Insufficient balance errors: - field: balance reason: You do not have enough balance for this preview. timestamp: '2026-10-29T10:00:00Z' error_id: 2f0c7a9e-61b4-4c0e-9a51-3c1f0d7b8e21 '403': description: >- Your account is not active (for example a trial) or not on per-update pricing for this radar type — not charged. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: status: error code: 403 message: Preview not available errors: - field: radar_type reason: >- Previews are available only with per-update pricing for this radar type. timestamp: '2026-10-29T10:00:00Z' error_id: 2f0c7a9e-61b4-4c0e-9a51-3c1f0d7b8e21 '429': description: >- Rate limit exceeded — no preview was run and nothing was charged. Check `Retry-After` and slow down. headers: Retry-After: schema: type: integer description: Seconds until your budget is restored content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: status: error code: 429 message: Per-second burst limit exceeded. Retry after 1 second. errors: - field: rate_limit reason: burst timestamp: '2026-10-29T10:00:00Z' error_id: 2f0c7a9e-61b4-4c0e-9a51-3c1f0d7b8e21 '500': description: >- The preview could not be completed. In rare cases it may still have been charged; `GET /v1/account` shows your current balance. A retry is a new preview and is charged for the updates it returns. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: status: error code: 500 message: An internal server error occurred. errors: [] timestamp: '2026-10-29T10:00:00Z' error_id: 2f0c7a9e-61b4-4c0e-9a51-3c1f0d7b8e21 security: - ApiKeyAuth: [] components: schemas: RadarPreviewRequest: type: object required: - domain - radar_type properties: domain: type: string description: >- 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: type: string description: >- The radar type to preview. Only `company_new_hires` can be previewed for now; other types return 400 "Preview not available". enum: - company_new_hires limit: type: integer minimum: 1 maximum: 100 default: 3 description: >- 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`. example: 3 departments: type: array items: type: string description: >- Optional department filter, same values and rules as Create Company Radar. example: - Engineering seniorities: type: array items: type: string description: >- Optional seniority filter, same values and rules as Create Company Radar. example: - Director job_titles: type: string description: >- 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: type: string format: uri description: >- Optional LinkedIn company page URL, same rules as Create Company Radar (e.g., https://www.linkedin.com/company/stripe). webhook_url: type: string format: uri description: >- Accepted so you can send your create body unchanged. Checked as on create, then ignored. custom_fields: type: object additionalProperties: true description: >- Accepted so you can send your create body unchanged. Checked as on create, then ignored. RadarPreviewResponse: type: object required: - status - code - timestamp - message - preview_id - updates - usage properties: status: type: string enum: - success code: type: integer enum: - 200 timestamp: type: string format: date-time message: type: string description: >- "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: type: string format: uuid description: >- Identifier for this preview, for support requests. Previews are not stored as radars and do not appear in GET /v1/updates. updates: type: array description: >- Up to `limit` updates, newest first. Empty when nothing was returned. items: $ref: '#/components/schemas/RadarPreviewUpdate' usage: $ref: '#/components/schemas/RadarPreviewUsage' ErrorResponse: type: object required: - status - code - message - errors - timestamp - error_id properties: status: type: string enum: - error code: type: integer enum: - 400 - 401 - 402 - 403 - 404 - 409 - 429 - 500 - 503 message: type: string errors: type: array items: type: object required: - field - reason properties: field: type: string reason: type: string conflicting_radar_id: type: string format: uuid nullable: true timestamp: type: string format: date-time error_id: type: string format: uuid RadarPreviewUpdate: type: object required: - update_type - discovered_at - data - content properties: update_type: type: string enum: - preview_finding discovered_at: type: string format: date-time description: >- When we found this update — when it was stored, or the time of this preview for a fresh finding. The event's own date is in `content` (`start_date`). data: type: object required: - radar_type - domain properties: radar_type: type: string example: company_new_hires domain: type: string example: stripe.com content: type: object description: >- Same shape as the `content` of a company_new_hires radar update (see the New Hires webhook page). Items have no `update_id`, `record_id` or `radar_id`; `preview_id` is the only identifier. additionalProperties: true RadarPreviewUsage: type: object required: - unit_price_usd - consumed_usd - balance_remaining_usd properties: unit_price_usd: type: number description: >- USD price per returned update applied to this request. Returned even when no updates match; in that case, `consumed_usd` is zero. example: 0.14 consumed_usd: type: number description: >- Charged for this preview — the number of returned updates × `unit_price_usd`. Zero when nothing was returned. example: 0.42 balance_remaining_usd: type: number description: Your balance after this preview. example: 124.58 securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.