> ## 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.

# List Radars

> Retrieve all radars on your account, filtered by type, domain, or status.



## OpenAPI

````yaml api_specs.yaml GET /v1/radars
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:
    get:
      tags:
        - Radars
      summary: Get all radars
      description: >-
        Returns a list of all radars for the authenticated user, sorted by
        creation date (newest first). All query parameters are optional and can
        be combined — omitting them returns all radars up to the limit.


        Use `radar_id` to fetch one or more specific radars by ID. If a
        `radar_id` does not exist or does not belong to your account, it is
        silently excluded from results — no error is thrown. The `count` field
        always reflects the number of radars actually returned.
      operationId: listRadars
      parameters:
        - name: radar_id
          in: query
          description: >-
            Comma-separated list of radar IDs (UUID format, max 50). Returns
            only the specified radars. Can be combined with other filters. Radar
            IDs that don't exist or don't belong to your account are silently
            excluded.
          required: false
          schema:
            type: string
            example: uuid1,uuid2,uuid3
        - name: limit
          in: query
          description: >-
            Maximum number of radars to return. Leave empty to use the default
            value (50).
          required: false
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 1000
        - name: radar_type
          in: query
          description: Filter by radar type. Leave empty to return all types.
          required: false
          schema:
            type: string
            enum:
              - 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_posts
              - contact_social_engagements
              - industry_mentions
              - industry_funding_rounds
              - industry_new_companies
              - industry_job_openings
        - name: radar_status
          in: query
          description: >-
            Filter by radar status. 'active' indicates the radar is operational,
            'inactive' indicates it is not currently tracking or is in a grace
            period after deactivation.
          required: false
          schema:
            type: string
            enum:
              - active
              - inactive
            description: >-
              Filter by radar status. 'active' indicates the radar is
              operational, 'inactive' indicates it is not currently tracking or
              is in a grace period after deactivation.
            nullable: true
      responses:
        '200':
          description: Successfully retrieved radars
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - success
                  code:
                    type: integer
                    enum:
                      - 200
                  message:
                    type: string
                  count:
                    type: integer
                    description: Number of radars returned
                  limit:
                    type: integer
                    description: Limit used for the request
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        radar_id:
                          type: string
                          format: uuid
                        domain:
                          type: string
                        radar_type:
                          type: string
                          enum:
                            - 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_posts
                            - contact_social_engagements
                            - industry_mentions
                            - industry_funding_rounds
                            - industry_new_companies
                            - industry_job_openings
                        radar_status:
                          type: string
                          enum:
                            - active
                            - inactive
                          description: >-
                            Filter by radar status. 'active' indicates the radar
                            is operational, 'inactive' indicates it is not
                            currently tracking or is in a grace period after
                            deactivation.
                          nullable: true
                        webhook_url:
                          type: string
                          format: uri
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                        updates_since:
                          type: string
                          format: date-time
                          nullable: true
                          description: >-
                            Stored customer-supplied eligibility cutoff
                            normalized to UTC. Null when omitted; in that case
                            created_at is the effective cutoff.
                        deactivated_at:
                          type: string
                          format: date-time
                          nullable: true
                        next_charge_at:
                          type: string
                          format: date-time
                          nullable: true
                        custom_fields:
                          type: object
                          additionalProperties: true
                        profile_url:
                          type: string
                          format: uri
                          nullable: true
                          description: >-
                            LinkedIn company page URL if provided during radar
                            creation.
                  timestamp:
                    type: string
                    format: date-time
              example:
                status: success
                code: 200
                timestamp: '2024-03-20T10:15:30.000Z'
                message: Radars retrieved successfully
                count: 1
                limit: 50
                data:
                  - radar_id: 123e4567-e89b-12d3-a456-426614174000
                    radar_type: company_new_hires
                    domain: example.com
                    created_at: '2024-03-20T10:00:00.000Z'
                    deactivated_at: null
                    next_charge_at: '2024-04-20T10:00:00.000Z'
                    webhook_url: https://example.com/webhook
                    radar_status: active
                    custom_fields:
                      department: engineering
        '400':
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_radar_id:
                  summary: Invalid radar_id UUID
                  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 IDs
                  value:
                    status: error
                    code: 400
                    message: radar_id limit exceeded
                    errors:
                      - field: radar_id
                        reason: Maximum 50 IDs allowed per request, got 51.
                    timestamp: '2026-04-23T17:05:26.000Z'
                    error_id: f72ac8d3-4bca-4f4c-b14a-30af90e3eac2
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - error
                  code:
                    type: integer
                    enum:
                      - 401
                  message:
                    type: string
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        reason:
                          type: string
                  timestamp:
                    type: string
                    format: date-time
              example:
                status: error
                code: 401
                message: Authentication required
                errors:
                  - field: x-api-key
                    reason: Missing or invalid API key
                timestamp: '2026-04-23T17:05:26.000Z'
                error_id: f72ac8d3-4bca-4f4c-b14a-30af90e3eac2
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: error
                code: 403
                message: Insufficient permissions
                errors:
                  - field: user
                    reason: You do not have permission to list radars
                timestamp: '2026-04-23T17:05:26.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'
              example:
                status: error
                code: 500
                message: An internal server error occurred.
                errors: []
                timestamp: '2026-04-23T17:05:26.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

````