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

# Update Competitor Team Member

> Monitor or pause one person at a competitor

Change one person's status.

* `monitored` resumes a **Paused** person, monitors someone pending, or restores someone
  you removed. On someone already monitored whose role changed (`function_changed_at` is set, shown
  as "Changed role: keep or remove"), it keeps them and clears the flag.
* `paused` stops collecting the person's activity and frees their slot. Their history stays.

Monitoring someone takes a slot. When every slot is in use the answer is `409 NO_SLOT`: pause
someone else first (or [swap](https://docs.clustr-ai.com/api-reference/swap-competitor-people.md) the two in one call), or
contact Clustr to raise your limit. Someone who left the competitor cannot be monitored
(`409 PERSON_LEFT`).

```bash cURL theme={null}
curl -X PATCH https://api.clustr-ai.com/api/public/competitors/cmp_r0jpyyqyeh0txpgdhb604j2g9s/tracked-persons/ctp_q3zg328tqgcw33xj4v2ahrcfeq \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "monitored" }'
```

```python Python theme={null}
import requests

requests.patch(
    "https://api.clustr-ai.com/api/public/competitors/cmp_r0jpyyqyeh0txpgdhb604j2g9s/tracked-persons/ctp_q3zg328tqgcw33xj4v2ahrcfeq",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"status": "monitored"},
)
```

```javascript JavaScript theme={null}
await fetch("https://api.clustr-ai.com/api/public/competitors/cmp_r0jpyyqyeh0txpgdhb604j2g9s/tracked-persons/ctp_q3zg328tqgcw33xj4v2ahrcfeq", {
  method: "PATCH",
  headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ status: "monitored" }),
});
```

```json 200 theme={null}
{
  "success": true,
  "data": {
    "tracked_person": {
      "clustr_competitor_tracked_person_id": "ctp_q3zg328tqgcw33xj4v2ahrcfeq",
      "clustr_competitor_id": "cmp_r0jpyyqyeh0txpgdhb604j2g9s",
      "clustr_person_id": "per_jzypgvc4wm1qqmh076ewd8ys7h",
      "id": "5d2f8a1c-7b3e-4c9a-8f1d-2e6b0a4c9d71",
      "competitor_id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "person_linkedin_id": "jane-doe",
      "full_name": "Jane Doe",
      "title": "Account Executive",
      "function": "sales",
      "status": "monitored",
      "source": "refresh",
      "monitored_since": "2026-10-08T09:00:00Z",
      "interactions_30d": 0
    },
    "slot_usage": { "used": 183, "total": 200, "paused": 3, "pending": 1, "plan": "l200", "active": 183, "limit": 200 }
  }
}
```

```json 409 theme={null}
{
  "success": false,
  "error": { "message": "No slot left: 1 needed, 0 free. Pause someone else, or contact Clustr to raise the limit.", "code": "NO_SLOT" }
}
```


## OpenAPI

````yaml PATCH /competitors/{id}/tracked-persons/{personID}
openapi: 3.1.0
info:
  title: Clustr Public API
  description: >
    Programmatic access to your Clustr network: import connectors, search warm
    intros (opportunities), and manage target accounts.


    ## Authentication

    All endpoints require a Bearer token (API key) in the `Authorization`
    header.


    ```

    Authorization: Bearer <your_api_key>

    ```


    API keys can be created and managed from the [API settings
    page](https://app.clustr-ai.com/api).
  version: '1.0'
  contact:
    name: Clustr Support
    url: https://clustr-ai.com
servers:
  - url: https://api.clustr-ai.com/api/public
    description: Production
security:
  - BearerAuth: []
paths:
  /competitors/{id}/tracked-persons/{personID}:
    patch:
      tags:
        - Competitor Monitoring
      summary: Update Competitor Team Member
      description: >
        Change one person's status. `monitored` resumes a paused person,
        validates a

        joiner, restores someone you removed, or keeps someone already monitored
        after a

        role change (clears `function_changed_at`). It takes a slot when the
        person was not

        monitored (`409 NO_SLOT` at the limit). `paused` frees the slot. Someone
        who left

        the competitor cannot be monitored (`409 PERSON_LEFT`).
      operationId: updateCompetitorTeamMember
      parameters:
        - name: id
          in: path
          required: true
          description: >-
            The competitor's Clustr ID (`cmp_…`), from [List
            Competitors](/api-reference/list-competitors).

            The id from earlier responses also works.
          schema:
            type: string
          example: cmp_2jjbgcjq1bsja47j4vkeh1f7qg
        - name: personID
          in: path
          required: true
          description: >-
            The Team member's Clustr ID (`ctp_…`), from [List Competitor

            Team](/api-reference/list-competitor-team). Their `id` or
            `person_linkedin_id` from earlier

            responses also work.
          schema:
            type: string
          example: ctp_gxmc6tfpkx8crqz8teabr0dfjt
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - status
              properties:
                status:
                  type: string
                  description: '`monitored` or `paused`.'
                  enum:
                    - monitored
                    - paused
      responses:
        '200':
          description: The person, with their new status
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      tracked_person:
                        $ref: '#/components/schemas/CompetitorTeamMember'
                      slot_usage:
                        $ref: '#/components/schemas/SlotUsage'
        '401':
          description: Invalid or missing API key
        '404':
          description: Competitor or person not found
        '409':
          description: >-
            Every slot is in use (`NO_SLOT`), or the person left the competitor
            (`PERSON_LEFT`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    CompetitorTeamMember:
      type: object
      description: One person on a competitor's Team.
      properties:
        clustr_competitor_tracked_person_id:
          type: string
          description: >-
            The Team member's Clustr ID, for example
            `ctp_tbs7p5xv4s6s92stg1x7rbwqx3`. Use it to refer to

            this Team member.
          example: ctp_tbs7p5xv4s6s92stg1x7rbwqx3
        clustr_competitor_id:
          type: string
          description: >-
            The competitor's Clustr ID, for example
            `cmp_7vj0tzfqk43c02nvjerwcx1hwq`.
          example: cmp_7vj0tzfqk43c02nvjerwcx1hwq
        clustr_person_id:
          type: string
          description: >-
            The person's Clustr ID, for example
            `per_4yg0p90t56h93jw357xf9a8s6b`.
          example: per_4yg0p90t56h93jw357xf9a8s6b
        clustr_new_account_id:
          type: string
          description: >-
            The Clustr ID of the account they moved to, for example
            `acc_yhhrbahsgqx6e5sjdq5z91tra1`.
          example: acc_yhhrbahsgqx6e5sjdq5z91tra1
        id:
          type: string
          description: >-
            Kept for integrations built before Clustr IDs. New integrations
            should use `clustr_competitor_tracked_person_id`.
        competitor_id:
          type: string
          description: >-
            Kept for integrations built before Clustr IDs. New integrations
            should use `clustr_competitor_id`.
        person_linkedin_id:
          type: string
        full_name:
          type: string
          example: Jane Doe
        title:
          type: string
          example: Account Executive
        headline:
          type: string
        avatar_url:
          type: string
        role_bucket:
          type: string
          enum:
            - founder
            - exec
            - am
            - csm
            - ae
            - bdr
            - other
          example: ae
        priority:
          type: integer
          description: >-
            The person's rank on the Team roster: 1 for a founder or executive
            (and anyone added manually), 2 for an AM or CSM, 3 for an AE, 4 for
            a BDR and 5 for anyone else.
          example: 3
        source:
          type: string
          enum:
            - search
            - manual
            - refresh
            - employee_list
          description: >-
            How the person joined the Team: `search` (shown as Auto extraction),
            `manual` or `employee_list` (shown as Manual addition), or `refresh`
            (shown as Detected at refresh).
        status:
          type: string
          enum:
            - monitored
            - paused
            - pending
            - left
            - removed
          description: >-
            `monitored`: the person takes a slot and their activity is
            collected. `paused`, `pending` (shown as To validate) and `left`
            take no slot. `removed` people appear only when the request asks for
            them.
        function:
          type: string
          enum:
            - sales
            - cs
            - other
        monitored_since:
          type: string
          format: date-time
          nullable: true
          description: When the person last became monitored, shown as Added on.
        paused_reason:
          type: string
          nullable: true
          enum:
            - no_slot
            - manual
        left_at:
          type: string
          format: date-time
          nullable: true
        new_company_name:
          type: string
          nullable: true
        new_company_linkedin_id:
          type: string
          nullable: true
        function_changed_at:
          type: string
          format: date-time
          nullable: true
          description: Set when their title moved outside Sales and CS.
        function_changed_title:
          type: string
          nullable: true
        interactions_30d:
          type: integer
          description: Retained interactions over the last 30 days.
          example: 14
        linkedin_url:
          type: string
        competitor_name:
          type: string
          description: The competitor's name. Present on List Competitor People only.
        relationship:
          type: string
          enum:
            - employee
            - investor
            - partner
            - advisor
            - other
          description: >-
            How someone added by hand is tied to the competitor. Absent for
            someone the team search found.
        still_employed:
          type: boolean
        excluded_at:
          type: string
          format: date-time
          description: Set when someone removed them from the Team.
        last_activity_at:
          type: string
          format: date-time
          description: Their latest engagement Clustr saw.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    SlotUsage:
      type: object
      description: >-
        Your competitor monitoring slots. Each monitored person takes one slot,
        whatever the competitor. The limit comes from your workspace's plan,
        which Clustr sets.
      properties:
        used:
          type: integer
          description: How many people are monitored.
          example: 182
        total:
          type: integer
          description: The slot limit.
          example: 200
        paused:
          type: integer
          description: How many people are paused, for lack of a slot or manually.
          example: 12
        pending:
          type: integer
          description: How many joiners are waiting for you to validate them.
          example: 3
        plan:
          type: string
          enum:
            - s50
            - m100
            - l200
            - custom
          example: l200
        active:
          type: integer
          description: The same count as `used`.
          example: 182
        limit:
          type: integer
          description: The same limit as `total`.
          example: 200
    ErrorResponse:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            message:
              type: string
              example: Invalid request body
            code:
              type: string
              example: BAD_REQUEST
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: The API key you created on the API settings page of the Clustr app.

````

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