> ## Documentation Index
> Fetch the complete documentation index at: https://docs.airscale.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get a new hire monitor

> Retrieve one monitor, its company list, and its latest 100 new hires. Rate limit: 120 requests per fixed minute per API key, shared by all new hire monitor endpoints.

> [!NOTE]
>
> New hire monitoring requires a **V2 workspace API key**. Legacy V1 API keys are not supported by these endpoints. Monitors and their credits belong to the V2 workspace associated with the key.

Retrieve one monitor by `monitor_id`. The response contains the monitor, its companies sorted by URL, and up to the latest 100 events ordered newest first.

> [!NOTE]
>
> `new_hire_count` and `unread_event_count` cover every event, not only the 100-event preview. Preview events have no `webhook` receipt; use [List new hire events](https://docs.airscale.io/api-reference/new-hire-monitors/events.md) for receipts, filters, and pagination.

Each company has `identifier` (the lower-case slug or numeric ID from its URL), `linkedin_url`, `linkedin_company_id`, `name`, `last_checked_at`, and `status`: `pending` until it is resolved, then `resolved`, or `unresolved` when the company could not be found. An unresolved company pauses the monitor with `run_block_reason: "unresolved_companies"`. A market monitor returns an empty `companies` array.

The monitor reports `baseline_completed_at`, `next_check_at`, and `last_successful_check_at` as ISO 8601 timestamps, or `null`. A paused monitor has no next check scheduled. `run_block_reason` explains why checks are not progressing and `results_status` with `results_error` explains why found new hires are not yet delivered to the results table.

## Next step

Use [Add companies](https://docs.airscale.io/api-reference/new-hire-monitors/companies/add.md) to extend a company-list monitor.


## OpenAPI

````yaml openapi.json GET /v1/new-hire-monitors/{monitor_id}
openapi: 3.1.0
info:
  title: Airscale Public API
  version: '2026-09-11'
  description: >-
    Search, enrich, resolve public business data, and monitor job changes with
    Airscale.
  x-airscale-source-repository: ViceScale/airscale-code
  x-airscale-source-sha: 1de19e1b70a052a4b8d9c2075021a7e5e7a94d51
servers:
  - url: https://api.airscale.io
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Search and discovery
    description: Search people, companies, and the web.
  - name: Contact data
    description: Find professional and personal contact data.
  - name: Profiles and reverse lookup
    description: Extract profiles or resolve a person from known contact data.
  - name: Post engagement
    description: Retrieve and enrich people who liked or commented on LinkedIn posts.
  - name: LinkedIn content
    description: >-
      Search LinkedIn posts, read profile and company feeds, and retrieve
      profile comments and comment reactions.
  - name: Job change monitoring
    description: Track LinkedIn profiles and receive job-change events.
  - name: New hire monitoring
    description: Watch companies or the market for people who start a matching role.
  - name: Post engagement monitoring
    description: >-
      Follow LinkedIn company pages and profiles and receive the people who
      engage with their posts.
  - name: Account
    description: Inspect workspace account state.
  - name: Miscellaneous
    description: >-
      Find website technologies and check WhatsApp availability, Meta ads, and
      email deliverability.
paths:
  /v1/new-hire-monitors/{monitor_id}:
    get:
      tags:
        - New hire monitoring
      summary: Get a monitor with companies and recent new hires
      description: >-
        Returns one monitor, its company list, and up to the latest 100 new hire
        events ordered newest first. Events in this preview have no webhook
        receipt; use the events endpoint for receipts and pagination. Requires a
        V2 workspace API key. Legacy V1 API keys are not supported. Monitors and
        their credits belong to the V2 workspace.
      operationId: getNewHireMonitor
      parameters:
        - name: monitor_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: 61111111-1111-4111-8111-111111111111
      responses:
        '200':
          description: The monitor detail.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - monitor
                  - companies
                  - events
                properties:
                  monitor:
                    $ref: '#/components/schemas/NewHireMonitor'
                  companies:
                    type: array
                    items:
                      $ref: '#/components/schemas/NewHireCompany'
                    description: >-
                      The monitor's company list, sorted by URL. Empty for a
                      market monitor.
                  events:
                    type: array
                    maxItems: 100
                    items:
                      $ref: '#/components/schemas/NewHireEvent'
              examples:
                success:
                  summary: Successful response
                  value:
                    monitor:
                      id: 61111111-1111-4111-8111-111111111111
                      name: Target accounts
                      frequency: weekly
                      status: active
                      audience: companies
                      legacy: false
                      filters:
                        job_titles:
                          - VP Sales
                          - Head of Sales
                        excluded_job_titles: []
                        title_match: strict
                        seniorities: []
                        hire_types:
                          - external
                        industries: []
                        company_size: null
                        company_location: null
                        person_location: null
                      results_table_id: 64444444-4444-4444-8444-444444444444
                      results_status: ready
                      results_error: null
                      baseline_completed_at: '2026-11-02T10:05:00.000Z'
                      next_check_at: '2026-11-09T10:05:00.000Z'
                      last_successful_check_at: '2026-11-02T10:05:00.000Z'
                      run_block_reason: null
                      created_at: '2026-11-02T10:00:00.000Z'
                      updated_at: '2026-11-02T10:05:00.000Z'
                      webhook_url: https://hooks.example.com/airscale/new-hires
                      webhook_configured: true
                      company_count: 2
                      unresolved_company_count: 0
                      new_hire_count: 1
                      unread_event_count: 1
                    companies:
                      - identifier: example-company
                        linkedin_url: https://www.linkedin.com/company/example-company
                        linkedin_company_id: '1035'
                        name: Example Company
                        status: resolved
                        last_checked_at: '2026-11-02T10:05:00.000Z'
                      - identifier: example-company-2
                        linkedin_url: https://www.linkedin.com/company/example-company-2
                        linkedin_company_id: '2036'
                        name: Example Company Two
                        status: resolved
                        last_checked_at: '2026-11-02T10:05:00.000Z'
                    events:
                      - id: 63333333-3333-4333-8333-333333333333
                        monitor_id: 61111111-1111-4111-8111-111111111111
                        detected_at: '2026-11-09T10:05:00.000Z'
                        hire_type: external
                        person:
                          name: Example Person
                          linkedin_url: https://www.linkedin.com/in/example-person
                          location: Paris, France
                        title: VP Sales
                        start_date: 2026-10
                        company:
                          name: Example Company
                          linkedin_company_id: null
                          linkedin_url: null
                        previous_title: Director of Sales
                        previous_company_name: Example Previous Company
                        read_at: null
        '401':
          $ref: '#/components/responses/MonitorUnauthorized'
        '404':
          description: monitor_not_found in this workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorApiError'
              examples:
                error:
                  summary: Error response
                  value:
                    error:
                      code: monitor_not_found
                      message: Monitor not found
        '429':
          description: >-
            The API key has exceeded 120 requests in the current minute across
            new hire monitor endpoints. Wait for the Retry-After seconds before
            retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                error:
                  summary: Error response
                  value:
                    error: Too Many Requests
                    message: 'Rate limit exceeded: 120 requests per minute'
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: string
              example: '60'
        '503':
          description: 'service_unavailable: new hire monitoring is temporarily unavailable.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorApiError'
components:
  schemas:
    NewHireMonitor:
      type: object
      additionalProperties: false
      required:
        - id
        - name
        - frequency
        - status
        - audience
        - legacy
        - filters
        - results_table_id
        - results_status
        - results_error
        - baseline_completed_at
        - next_check_at
        - last_successful_check_at
        - run_block_reason
        - created_at
        - updated_at
        - webhook_url
        - webhook_configured
        - company_count
        - unresolved_company_count
        - new_hire_count
        - unread_event_count
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        frequency:
          type: string
          enum:
            - daily
            - weekly
            - every_30_days
            - every_90_days
        status:
          type: string
          enum:
            - active
            - paused
        audience:
          type: string
          enum:
            - companies
            - market
        legacy:
          type: boolean
          description: >-
            true for monitors created in the app before role filters existed.
            They have filters: null and can be read, paused, resumed and
            renamed, but their companies can only be edited in the app.
        filters:
          description: >-
            The role and market filters set at creation, or null for a legacy
            monitor. Filters cannot be edited.
          oneOf:
            - $ref: '#/components/schemas/NewHireMonitorFilters'
            - type: 'null'
        results_table_id:
          type: string
          description: The Airscale results table that receives one row per new hire.
        results_status:
          type: string
          enum:
            - ready
            - pending
            - blocked
          description: >-
            Whether found new hires are delivered to the results table. pending:
            deliveries are waiting. blocked: see results_error.
        results_error:
          type:
            - string
            - 'null'
          description: >-
            Why found new hires are not yet delivered, for example
            insufficient_credits, results_table_deleted,
            table_row_limit_reached, results_columns_missing, or a temporary
            credit_settlement_busy or table_mutation_locked.
        baseline_completed_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When the first completed check recorded the baseline. null until it
            exists, and again after a company change resets it.
        next_check_at:
          type:
            - string
            - 'null'
          format: date-time
        last_successful_check_at:
          type:
            - string
            - 'null'
          format: date-time
        run_block_reason:
          type:
            - string
            - 'null'
          description: >-
            Why checks are not progressing, for example unresolved_companies,
            audience_needs_review, unsupported_location, or a temporary
            account_pool_unavailable.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        webhook_url:
          type:
            - string
            - 'null'
          format: uri
        webhook_configured:
          type: boolean
        company_count:
          type: integer
          minimum: 0
          maximum: 10000
          description: 0 for a market monitor.
        unresolved_company_count:
          type: integer
          minimum: 0
          description: Companies that are pending or could not be found.
        new_hire_count:
          type: integer
          minimum: 0
          description: Every delivered new hire, not only the 100-event preview.
        unread_event_count:
          type: integer
          minimum: 0
    NewHireCompany:
      type: object
      additionalProperties: false
      required:
        - identifier
        - linkedin_url
        - linkedin_company_id
        - name
        - status
        - last_checked_at
      properties:
        identifier:
          type: string
          description: >-
            The lower-case company slug or numeric company ID from the LinkedIn
            URL. Use it to remove the company.
        linkedin_url:
          type: string
          format: uri
        linkedin_company_id:
          type:
            - string
            - 'null'
          description: The numeric LinkedIn company ID once the company is resolved.
        name:
          type:
            - string
            - 'null'
        status:
          type: string
          enum:
            - pending
            - resolved
            - unresolved
        last_checked_at:
          type:
            - string
            - 'null'
          format: date-time
    NewHireEvent:
      type: object
      additionalProperties: false
      required:
        - id
        - monitor_id
        - detected_at
        - hire_type
        - person
        - title
        - start_date
        - company
        - previous_title
        - previous_company_name
        - read_at
      properties:
        id:
          type: string
          format: uuid
        monitor_id:
          type: string
          format: uuid
        detected_at:
          type: string
          format: date-time
        hire_type:
          type:
            - string
            - 'null'
          enum:
            - external
            - internal
            - null
        person:
          $ref: '#/components/schemas/NewHirePerson'
        title:
          type:
            - string
            - 'null'
        start_date:
          type:
            - string
            - 'null'
          pattern: ^\d{4}-\d{2}$
          description: The reported start month (YYYY-MM), or null.
        company:
          $ref: '#/components/schemas/NewHireEventCompany'
        previous_title:
          type:
            - string
            - 'null'
        previous_company_name:
          type:
            - string
            - 'null'
        read_at:
          type:
            - string
            - 'null'
          format: date-time
    MonitorApiError:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: object
          additionalProperties: false
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
    Error:
      type: object
      additionalProperties: true
      properties:
        error:
          type: string
        message:
          type: string
    NewHireMonitorFilters:
      type: object
      additionalProperties: false
      required:
        - job_titles
        - excluded_job_titles
        - title_match
        - seniorities
        - hire_types
        - industries
        - company_size
        - company_location
        - person_location
      properties:
        job_titles:
          type: array
          items:
            type: string
        excluded_job_titles:
          type: array
          items:
            type: string
        title_match:
          type: string
          enum:
            - strict
            - loose
        seniorities:
          type: array
          items:
            type: string
            enum:
              - individual_contributor
              - manager
              - director
              - executive
          description: Empty means every seniority.
        hire_types:
          type: array
          items:
            type: string
            enum:
              - external
              - internal
        industries:
          type: array
          items:
            type: string
        company_size:
          type:
            - string
            - 'null'
          enum:
            - 1-10
            - 11-50
            - 51-200
            - 201-500
            - 501-1000
            - 1001-5000
            - 5001-10000
            - 10001+
            - null
        company_location:
          type:
            - string
            - 'null'
        person_location:
          type:
            - string
            - 'null'
    NewHirePerson:
      type: object
      additionalProperties: false
      required:
        - name
        - linkedin_url
        - location
      properties:
        name:
          type:
            - string
            - 'null'
        linkedin_url:
          type:
            - string
            - 'null'
        location:
          type:
            - string
            - 'null'
    NewHireEventCompany:
      type: object
      additionalProperties: false
      required:
        - name
        - linkedin_company_id
        - linkedin_url
      properties:
        name:
          type:
            - string
            - 'null'
        linkedin_company_id:
          type:
            - string
            - 'null'
        linkedin_url:
          type:
            - string
            - 'null'
          description: >-
            https://www.linkedin.com/company/{linkedin_company_id}, or null when
            the ID is unknown.
  responses:
    MonitorUnauthorized:
      description: >-
        A missing Bearer token returns
        {"error":"Unauthorized","message":"Missing or invalid bearer token"}. An
        unknown API key returns invalid_api_key.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/MonitorApiError'
              - $ref: '#/components/schemas/Error'
          examples:
            invalidKey:
              summary: Unknown API key
              value:
                error:
                  code: invalid_api_key
                  message: The API key is not valid
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: >-
        Use an Airscale workspace API key. Never expose the key in client-side
        code.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.