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

# Swap Competitor People

> Pause one monitored person and monitor another in one step

Move a slot from one person to another: pause a monitored person and monitor someone else in the
same step, so nothing is refused for lack of a slot in between. The two may be at different
competitors. The person to monitor can be **Paused**, pending or removed; someone who left
the competitor cannot be monitored (`409 PERSON_LEFT`).

The paused person keeps their history and shows as Paused. Find both ids with
[List Competitor People](https://docs.clustr-ai.com/api-reference/list-competitor-people.md).

```bash cURL theme={null}
curl -X POST https://api.clustr-ai.com/api/public/competitor-people/swap \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pause_person_id": "ctp_q3zg328tqgcw33xj4v2ahrcfeq",
    "monitor_person_id": "ctp_d73mfdcms7k6qtzyjqwrkdjh5e"
  }'
```

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

requests.post(
    "https://api.clustr-ai.com/api/public/competitor-people/swap",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "pause_person_id": "ctp_q3zg328tqgcw33xj4v2ahrcfeq",
        "monitor_person_id": "ctp_d73mfdcms7k6qtzyjqwrkdjh5e",
    },
)
```

```javascript JavaScript theme={null}
await fetch("https://api.clustr-ai.com/api/public/competitor-people/swap", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    pause_person_id: "ctp_q3zg328tqgcw33xj4v2ahrcfeq",
    monitor_person_id: "ctp_d73mfdcms7k6qtzyjqwrkdjh5e",
  }),
});
```

```json 200 theme={null}
{
  "success": true,
  "data": {
    "paused": {
      "clustr_competitor_tracked_person_id": "ctp_q3zg328tqgcw33xj4v2ahrcfeq",
      "id": "5d2f8a1c-7b3e-4c9a-8f1d-2e6b0a4c9d71",
      "full_name": "Jane Doe",
      "status": "paused",
      "paused_reason": "manual"
    },
    "monitored": {
      "clustr_competitor_tracked_person_id": "ctp_d73mfdcms7k6qtzyjqwrkdjh5e",
      "id": "9a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
      "full_name": "Hélène Martin",
      "status": "monitored",
      "monitored_since": "2026-10-08T09:00:00Z"
    },
    "slot_usage": { "used": 200, "total": 200, "paused": 12, "pending": 0, "plan": "l200", "active": 200, "limit": 200 }
  }
}
```


## OpenAPI

````yaml POST /competitor-people/swap
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:
  /competitor-people/swap:
    post:
      tags:
        - Competitor Monitoring
      summary: Swap Competitor People
      description: >
        Pause one monitored person and monitor another in one step, so the slot
        moves

        between them. They may be at different competitors.
      operationId: swapCompetitorPeople
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - pause_person_id
                - monitor_person_id
              properties:
                pause_person_id:
                  type: string
                  description: >-
                    The Clustr ID (`ctp_…`) of a monitored person, as List
                    Competitor Team returns it. The id from

                    earlier responses also works.
                monitor_person_id:
                  type: string
                  description: >-
                    The Clustr ID (`ctp_…`) of the person to monitor in their
                    place, as List Competitor Team returns

                    it. The id from earlier responses also works.
      responses:
        '200':
          description: Both people, with their new statuses.
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      paused:
                        $ref: '#/components/schemas/CompetitorTeamMember'
                      monitored:
                        $ref: '#/components/schemas/CompetitorTeamMember'
                      slot_usage:
                        $ref: '#/components/schemas/SlotUsage'
        '401':
          description: Invalid or missing API key
        '404':
          description: Person not found
        '409':
          description: >-
            The person to monitor left the competitor (`PERSON_LEFT`), or the
            person to pause is not monitored
          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.