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

# Update a post engagement monitor

> Change a monitor's settings or filters, pause or resume checks, change its webhook, or rotate the signing secret. Rate limit: 120 requests per fixed minute per API key, shared by all post engagement monitor endpoints.

> [!NOTE]
>
> Post engagement 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.

Update any combination of `name`, `frequency` (`daily` or `weekly`), `action` (`pause` or `resume`), `engagement_types`, `include_existing_engagers`, `filters`, `webhook_url` (HTTPS URL or `null`), and `rotate_signing_secret: true`. Sources change through [Add sources](https://docs.airscale.io/api-reference/post-engagement-monitors/sources/add.md) and [Remove a source](https://docs.airscale.io/api-reference/post-engagement-monitors/sources/remove.md); any other field returns `422 invalid_monitor_update`.

## Pause and resume

**Pause** stops checks and holds queued webhooks until the monitor is resumed. **Resume** schedules a check immediately and requires monitoring to be available (`503 monitoring_not_enabled`) and at least 0.2 credits (`402 insufficient_credits`).

## Settings

* Changing `frequency` schedules the next check one period from now.
* Changing `engagement_types` or `filters` restarts coverage. People already delivered stay delivered and are never charged again. `filters` replaces the whole filter object; omitted lists become empty.
* Turning `include_existing_engagers` on delivers previously seen engagers on the next pass and charges them.

## Change the webhook or recover a lost signing secret

* Setting or changing `webhook_url`, or sending `rotate_signing_secret: true`, returns a new one-time `signing_secret` with `signing_secret_warning`. Store it immediately.
* `{"webhook_url": null}` disables the webhook and clears the secret. Rotating without a webhook returns `422 webhook_not_configured`; combining rotation with `webhook_url: null` returns `422 invalid_monitor_update`.
* Repeating the same URL without rotation returns no secret.

Queued deliveries made for the old configuration are cancelled (`webhook_configuration_changed`); use redelivery to send them again. If a delivery is being sent at that moment, the edit returns `409 webhook_delivery_in_progress` and changes nothing; retry shortly. Configuration changes never spend credits.

## Next step

Use [Redeliver a webhook](https://docs.airscale.io/api-reference/post-engagement-monitors/engagers/redeliver.md) after changing the webhook URL.


## OpenAPI

````yaml openapi.json PATCH /v1/post-engagement-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/post-engagement-monitors/{monitor_id}:
    patch:
      tags:
        - Post engagement monitoring
      summary: Update, pause, or resume a monitor, or change its webhook
      description: >-
        Changes the name, frequency, engagement types, existing-engager setting
        or filters, pauses or resumes checks, sets, changes, or disables the
        webhook, or rotates the signing secret. Fields can be combined in one
        request. Sources change through the sources endpoints. Setting a new
        webhook URL or rotating returns a one-time signing_secret. Requires a V2
        workspace API key. Legacy V1 API keys are not supported. Monitors and
        their credits belong to the V2 workspace.
      operationId: updatePostEngagementMonitor
      parameters:
        - name: monitor_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: 71111111-1111-4111-8111-111111111111
      requestBody:
        required: true
        description: >-
          Send at least one supported field. Any other field, including sources,
          is rejected.
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              minProperties: 1
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 120
                frequency:
                  type: string
                  enum:
                    - daily
                    - weekly
                action:
                  type: string
                  enum:
                    - pause
                    - resume
                engagement_types:
                  type: array
                  minItems: 1
                  maxItems: 2
                  uniqueItems: true
                  items:
                    type: string
                    enum:
                      - reactions
                      - comments
                include_existing_engagers:
                  type: boolean
                filters:
                  type: object
                  additionalProperties: false
                  description: >-
                    Replaces the monitor's filters. Omitted filter lists become
                    empty.
                  properties:
                    titles:
                      type: array
                      maxItems: 50
                      items:
                        type: string
                        minLength: 1
                        maxLength: 200
                      default: []
                    locations:
                      type: array
                      maxItems: 50
                      items:
                        type: string
                        minLength: 1
                        maxLength: 200
                      default: []
                    excluded_company_urls:
                      type: array
                      maxItems: 100
                      items:
                        type: string
                        maxLength: 500
                      default: []
                      description: LinkedIn company URLs whose employees are left out.
                webhook_url:
                  type:
                    - string
                    - 'null'
                  format: uri
                  maxLength: 2048
                  description: >-
                    Set or change the webhook (a public HTTPS URL without
                    embedded credentials), or send null to disable it and clear
                    its signing secret. Setting a new URL returns a fresh
                    signing_secret.
                rotate_signing_secret:
                  type: boolean
                  const: true
                  description: >-
                    Generate a new signing secret for the enabled webhook.
                    Cannot be combined with webhook_url: null.
            examples:
              pause:
                summary: Pause checks
                value:
                  action: pause
              resume:
                summary: Resume checks
                value:
                  action: resume
              settings:
                summary: Change the schedule and filters
                value:
                  frequency: weekly
                  engagement_types:
                    - comments
                  filters:
                    titles:
                      - Founder
                    locations: []
                    excluded_company_urls: []
              webhook:
                summary: Set a webhook and get a new signing secret
                value:
                  webhook_url: https://hooks.example.com/airscale/engagers
              rotate:
                summary: Rotate the signing secret
                value:
                  rotate_signing_secret: true
              disableWebhook:
                summary: Disable the webhook
                value:
                  webhook_url: null
      responses:
        '200':
          description: >-
            The updated monitor. signing_secret and signing_secret_warning
            appear only when a new secret was generated.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - monitor
                properties:
                  monitor:
                    $ref: '#/components/schemas/PostEngagementMonitor'
                  signing_secret:
                    type: string
                    description: >-
                      Present only when the request set a new webhook URL or
                      rotated the secret. Store it immediately.
                  signing_secret_warning:
                    type: string
              examples:
                success:
                  summary: Successful response
                  value:
                    monitor:
                      id: 71111111-1111-4111-8111-111111111111
                      name: Competitor audiences
                      status: active
                      frequency: daily
                      engagement_types:
                        - reactions
                        - comments
                      include_existing_engagers: false
                      filters:
                        titles:
                          - VP
                          - Head of
                        locations:
                          - France
                        excluded_company_urls:
                          - https://www.linkedin.com/company/example-company
                      results_table_id: 74444444-4444-4444-8444-444444444444
                      results_status: ready
                      results_error: null
                      next_check_at: '2026-11-03T09:00:00.000Z'
                      last_checked_at: '2026-11-02T09:00:00.000Z'
                      last_error: null
                      webhook_url: https://hooks.example.com/airscale/engagers
                      webhook_configured: true
                      source_count: 2
                      engager_count: 37
                      unread_engager_count: 5
                      created_at: '2026-11-02T08:58:00.000Z'
                      updated_at: '2026-11-02T09:00:00.000Z'
                    signing_secret: example-signing-secret
                    signing_secret_warning: Store this secret now. It is not returned again.
        '400':
          description: >-
            The request body is missing or is not valid JSON. The public API
            returns {"error":"Invalid JSON"}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                error:
                  summary: Error response
                  value:
                    error: Invalid JSON
        '401':
          $ref: '#/components/responses/MonitorUnauthorized'
        '402':
          description: 'insufficient_credits: resuming requires at least 0.2 credits.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorApiError'
        '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
        '409':
          description: >-
            webhook_delivery_in_progress: a webhook send is in flight. The
            configuration was not changed; retry after the delivery settles.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorApiError'
        '413':
          description: The JSON request body exceeds the 256 KiB (262,144 bytes) limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: >-
            invalid_monitor_update (for example no supported field, an unknown
            field, invalid filters, a webhook_url that is not a public HTTPS
            destination, or rotation combined with webhook_url: null) or
            webhook_not_configured when rotating without a webhook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorApiError'
        '429':
          description: >-
            The API key has exceeded 120 requests in the current minute across
            post engagement 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: >-
            monitoring_not_enabled when resuming while post engagement
            monitoring is closed, or service_unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorApiError'
components:
  schemas:
    PostEngagementMonitor:
      type: object
      additionalProperties: false
      required:
        - id
        - name
        - status
        - frequency
        - engagement_types
        - include_existing_engagers
        - filters
        - results_table_id
        - results_status
        - results_error
        - next_check_at
        - last_checked_at
        - last_error
        - webhook_url
        - webhook_configured
        - source_count
        - engager_count
        - unread_engager_count
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        status:
          type: string
          enum:
            - active
            - paused
        frequency:
          type: string
          enum:
            - daily
            - weekly
        engagement_types:
          type: array
          items:
            type: string
            enum:
              - reactions
              - comments
        include_existing_engagers:
          type: boolean
        filters:
          type: object
          additionalProperties: false
          required:
            - titles
            - locations
            - excluded_company_urls
          properties:
            titles:
              type: array
              items:
                type: string
            locations:
              type: array
              items:
                type: string
            excluded_company_urls:
              type: array
              items:
                type: string
        results_table_id:
          type: string
          description: >-
            The Airscale results table that receives one row per delivered
            engager.
        results_status:
          type: string
          enum:
            - ready
            - pending
            - blocked
          description: >-
            ready, pending (engagers waiting for delivery) or blocked (see
            results_error).
        results_error:
          type:
            - string
            - 'null'
          description: >-
            Why delivery is blocked, for example insufficient_credits,
            results_table_deleted, table_row_limit_reached or
            results_columns_missing.
        next_check_at:
          type:
            - string
            - 'null'
          format: date-time
        last_checked_at:
          type:
            - string
            - 'null'
          format: date-time
        last_error:
          type:
            - string
            - 'null'
          description: A short code when the last check could not complete.
        webhook_url:
          type:
            - string
            - 'null'
          format: uri
        webhook_configured:
          type: boolean
        source_count:
          type: integer
          minimum: 0
          description: Active sources.
        engager_count:
          type: integer
          minimum: 0
          description: Engagers delivered to the results table.
        unread_engager_count:
          type: integer
          minimum: 0
          description: Exact count, independent of any page size.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Error:
      type: object
      additionalProperties: true
      properties:
        error:
          type: string
        message:
          type: string
    MonitorApiError:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: object
          additionalProperties: false
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
  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.