> ## 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. # Poll Updates > Fetch radar findings and failures via cursor-based polling. ## OpenAPI ````yaml api_specs.yaml GET /v1/updates 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/updates: get: tags: - Updates summary: Poll for radar updates description: >- Returns a paginated list of radar updates for the authenticated account. Updates are the same payloads that would be delivered via webhook — use this endpoint to pull updates on demand instead of (or in addition to) receiving them via webhook. ## Pagination Results are returned in reverse chronological order (newest first). Use cursor-based pagination to walk through all updates: 1. Call the endpoint — receive `updates`, `has_more`, and `next_cursor` 2. If `has_more: true`, pass `next_cursor` as the `cursor` parameter on the next call 3. Repeat until `has_more: false` Cursors are opaque — do not parse them or persist them across sessions. ## Incremental Polling To poll only for new updates since your last sync, use the `since` parameter with the `discovered_at` value from the last update you processed: ``` GET /v1/updates?since=2026-04-13T21:00:00Z ``` ## Payload Shape Each item in the `updates` array is identical to a webhook payload delivery. ## Data Retention Updates are retained for **60 days** from the `discovered_at` date. Records older than 60 days are automatically purged. Use the `since` parameter for incremental polling to avoid missing updates near the retention boundary. operationId: getUpdates parameters: - name: radar_id in: query required: false description: >- Filter by one or more radar IDs. Comma-separated UUIDs, maximum 10. If a radar_id belongs to a different account, it is silently ignored (returns 0 results for that ID). schema: type: string example: >- bd3d93e1-9f97-4ed2-964b-a4c71aa2dab0,c9e1f3a2-88bc-41de-b321-99abc1234567 - name: radar_type in: query required: false description: >- Filter by one or more radar types. Comma-separated. Valid values: `company_new_hires`, `company_job_openings`, `company_promotions`, `company_reviews`, `company_mentions`, `company_social_posts`, `company_social_posts_cxo`, `company_social_engagements`, `contact_job_changes`, `contact_social_engagements`, `contact_social_posts`, `industry_mentions`, `industry_funding_rounds`, `industry_new_companies`, `industry_job_openings`. schema: type: string example: company_new_hires,company_promotions - name: update_type in: query required: false description: >- Filter by update type. Comma-separated. Valid values: `radar_finding`, `radar_failure`. Defaults to `radar_finding` only — you must explicitly opt in to receive `radar_failure` updates. schema: type: string default: radar_finding example: radar_finding - name: domain in: query required: false description: >- Filter by one or more tracked domains. Comma-separated, maximum 10. Only applicable to company radar types — industry radar updates do not have a domain. schema: type: string example: stripe.com,acme.com - name: since in: query required: false description: >- Return only updates with a `discovered_at` at or after this timestamp. Accepts any valid ISO 8601 date or datetime string. Use the `discovered_at` value from the last update you processed to implement incremental polling. schema: type: string format: date-time example: '2026-04-13T21:00:00.000Z' - name: cursor in: query required: false description: >- Pagination cursor returned as `next_cursor` from a previous response. Pass this to retrieve the next page of results. Cursors are opaque — do not parse or modify them. schema: type: string example: >- eyJyIjoiMjAyNi0wNC0xM1QyMToyMjo1OVoiLCJpIjoiZWZiZjdjNzctYzFhZS00YTBkLTg1YjYtMTE2Njc0ZTllMGIxIn0= - name: limit in: query required: false description: >- Maximum number of updates to return. Defaults to 25. Minimum 1, maximum 100. schema: type: integer default: 25 minimum: 1 maximum: 100 example: 25 responses: '200': description: Updates retrieved successfully content: application/json: schema: type: object properties: status: type: string enum: - success code: type: integer enum: - 200 message: type: string updates: type: array description: >- Array of update payloads. Each item is identical in shape to a webhook delivery payload. items: type: object properties: update_id: type: string format: uuid description: Unique identifier for this update event. record_id: type: string format: uuid description: >- ID of the underlying radar record that triggered this update. update_type: type: string enum: - radar_finding - radar_failure description: >- Type of update. `radar_finding` is a normal result. `radar_failure` indicates the radar could not be processed. discovered_at: type: string format: date-time description: >- Timestamp when this update was processed and approved for delivery. Use this value with the `since` parameter to implement incremental polling — store it after each sync and pass it on the next call. data: type: object description: Radar context — the radar that produced this update. properties: domain: type: string nullable: true description: >- The tracked domain. Null for industry radar types. radar_id: type: string format: uuid description: ID of the radar that produced this update. radar_type: type: string description: Type of the radar (e.g. `company_promotions`). custom_fields: type: object description: >- Custom fields attached to the radar at creation time. Useful for passing your own metadata (e.g. CRM IDs). next_charge_at: type: string format: date-time description: Next scheduled billing date for this radar. content: type: object description: >- The finding details. Shape varies by radar type — for example, a `company_promotions` update includes `full_name`, `current_title`, `previous_title`, and `profile_url`, while a `company_new_hires` update includes the new hire's name, title, and start date. has_more: type: boolean description: >- Whether more updates exist beyond this page. If true, pass `next_cursor` to retrieve the next page. next_cursor: type: string nullable: true description: >- Opaque cursor encoding the position of the last item on this page. Pass as `cursor` on the next request. Null when `has_more` is false. timestamp: type: string format: date-time examples: with_results: summary: Page of results with more available value: status: success code: 200 timestamp: '2026-04-14T10:00:00.000Z' message: Updates retrieved successfully updates: - update_id: efbf7c77-c1ae-4a0d-85b6-116674e9e0b1 record_id: 2b089d98-5d68-47e2-921d-a6403ec868a6 update_type: radar_finding discovered_at: '2026-04-13T21:22:59.000Z' data: domain: acme.com radar_id: bd3d93e1-9f97-4ed2-964b-a4c71aa2dab0 radar_type: company_promotions custom_fields: crm_id: acct_123 next_charge_at: '2026-05-13T06:11:53.000Z' content: full_name: Jane Smith first_name: Jane last_name: Smith profile_url: https://www.linkedin.com/in/janesmith current_title: Senior Software Engineer previous_title: Software Engineer promotion_date: '2026-03-01T00:00:00.000Z' country: United States has_more: true next_cursor: >- eyJyIjoiMjAyNi0wNC0xM1QyMToyMjo1OVoiLCJpIjoiZWZiZjdjNzctYzFhZS00YTBkLTg1YjYtMTE2Njc0ZTllMGIxIn0= last_page: summary: Final page — has_more false, next_cursor null value: status: success code: 200 timestamp: '2026-04-14T10:00:01.000Z' message: Updates retrieved successfully updates: [] has_more: false next_cursor: null '400': description: Invalid request parameters content: application/json: schema: type: object properties: status: type: string enum: - error code: type: integer enum: - 400 message: type: string errors: type: array items: type: object properties: field: type: string reason: type: string examples: invalid_cursor: summary: Invalid cursor value: status: error code: 400 message: Invalid cursor errors: [] timestamp: '2026-04-23T17:05:26.000Z' error_id: f72ac8d3-4bca-4f4c-b14a-30af90e3eac2 invalid_radar_type: summary: Invalid radar_type value value: status: error code: 400 message: >- Invalid radar_type value(s): company_hires. Check API docs for allowed values. errors: - field: radar_type reason: >- Invalid radar_type value(s): company_hires. Check API docs for allowed values. timestamp: '2026-04-23T17:05:26.000Z' error_id: f72ac8d3-4bca-4f4c-b14a-30af90e3eac2 invalid_radar_id: summary: Invalid radar_id format value: status: error code: 400 message: 'Invalid radar_id value(s): not-a-uuid' errors: - field: radar_id reason: 'The following are not valid UUIDs: not-a-uuid' timestamp: '2026-04-23T17:05:26.000Z' error_id: f72ac8d3-4bca-4f4c-b14a-30af90e3eac2 too_many_radar_ids: summary: Too many radar_id values value: status: error code: 400 message: radar_id accepts at most 10 values errors: - field: radar_id reason: radar_id accepts at most 10 values timestamp: '2026-04-23T17:05:26.000Z' error_id: f72ac8d3-4bca-4f4c-b14a-30af90e3eac2 invalid_since: summary: Invalid since timestamp value: status: error code: 400 message: since must be a valid ISO 8601 date errors: - field: since reason: since must be a valid ISO 8601 date timestamp: '2026-04-23T17:05:26.000Z' error_id: f72ac8d3-4bca-4f4c-b14a-30af90e3eac2 invalid_update_type: summary: Invalid update_type value value: status: error code: 400 message: >- Invalid update_type value(s): unknown_type. Valid values: radar_finding, radar_failure errors: - field: update_type reason: >- Invalid update_type value(s): unknown_type. Valid values: radar_finding, radar_failure timestamp: '2026-04-23T17:05:26.000Z' error_id: f72ac8d3-4bca-4f4c-b14a-30af90e3eac2 '401': description: Authentication required - Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missing_api_key: summary: Missing API key value: status: error code: 401 message: Missing API key errors: - field: x-api-key reason: API key is required timestamp: '2026-04-14T10:00:00.000Z' error_id: f72ac8d3-4bca-4f4c-b14a-30af90e3eac2 invalid_api_key: summary: Invalid API key value: status: error code: 401 message: Invalid API key format errors: - field: x-api-key reason: Invalid API key format timestamp: '2026-04-14T10:00:00.000Z' error_id: f72ac8d3-4bca-4f4c-b14a-30af90e3eac2 '429': description: >- Rate limit exceeded — no operation was performed. Check `Retry-After` to know when to retry, or `X-RateLimit-Remaining` to know your current budget. headers: Retry-After: schema: type: integer description: Seconds until your budget is restored X-RateLimit-Limit: schema: type: integer description: Your per-minute budget for this endpoint X-RateLimit-Remaining: schema: type: integer description: Tokens remaining right now content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: minute_limit: summary: Per-minute budget exhausted value: status: error code: 429 message: Per-minute rate limit exceeded. Retry after 45 seconds. errors: - field: rate_limit reason: minute timestamp: '2026-04-23T17:05:26.000Z' error_id: f72ac8d3-4bca-4f4c-b14a-30af90e3eac2 burst_limit: summary: Per-second burst limit hit value: status: error code: 429 message: Per-second burst limit exceeded. Retry after 1 second. errors: - field: rate_limit reason: burst timestamp: '2026-04-23T17:05:26.000Z' error_id: f72ac8d3-4bca-4f4c-b14a-30af90e3eac2 '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: server_error: summary: Internal server error value: status: error code: 500 message: An internal server error occurred. errors: [] timestamp: '2026-04-14T10:00:00.000Z' error_id: f72ac8d3-4bca-4f4c-b14a-30af90e3eac2 security: - ApiKeyAuth: [] components: schemas: 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 securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key ````