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

# List Competitor People

> Everyone tracked across all your competitors, with filters and a name search

Every person tracked at any of your competitors, in one list, with the same columns as
[List Competitor Team](https://docs.clustr-ai.com/api-reference/list-competitor-team.md) plus `competitor_name`, and the slot
counter. People you removed are left out unless `status` asks for them.

The name search ignores case and accents: `helene` finds "Hélène".

The list comes ordered pending first (normally nobody), then Monitored, Paused and Left, then by rank and name.

```bash cURL theme={null}
curl "https://api.clustr-ai.com/api/public/competitor-people?status=paused&function=sales&q=helene" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

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

requests.get(
    "https://api.clustr-ai.com/api/public/competitor-people",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"status": "paused", "function": "sales", "q": "helene"},
)
```

```javascript JavaScript theme={null}
await fetch("https://api.clustr-ai.com/api/public/competitor-people?status=paused&function=sales&q=helene", {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});
```

```json 200 theme={null}
{
  "success": true,
  "data": {
    "people": [
      {
        "clustr_competitor_tracked_person_id": "ctp_d73mfdcms7k6qtzyjqwrkdjh5e",
        "clustr_competitor_id": "cmp_r0jpyyqyeh0txpgdhb604j2g9s",
        "clustr_person_id": "per_pwf6z0866htjppk8va1djb15yz",
        "id": "9a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
        "competitor_id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "competitor_name": "Globex Inc",
        "person_linkedin_id": "helene-martin",
        "full_name": "Hélène Martin",
        "title": "Account Executive",
        "linkedin_url": "https://www.linkedin.com/in/helene-martin",
        "function": "sales",
        "status": "paused",
        "paused_reason": "no_slot",
        "source": "search",
        "monitored_since": null,
        "interactions_30d": 0
      }
    ],
    "total": 1,
    "slot_usage": { "used": 200, "total": 200, "paused": 12, "pending": 0, "plan": "l200", "active": 200, "limit": 200 }
  }
}
```


## OpenAPI

````yaml GET /competitor-people
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:
    get:
      tags:
        - Competitor Monitoring
      summary: List Competitor People
      description: >-
        Lists everyone tracked across all your competitors. Filter by
        competitor, function and status, and search by name, ignoring case and
        accents. Removed people appear only when `status` includes `removed`.
      operationId: listCompetitorPeople
      parameters:
        - name: competitor_id
          in: query
          description: >-
            Keeps the people at these competitors, by their Clustr IDs
            (`cmp_…`). Repeat the parameter or

            send a comma-separated list. The ids from earlier responses also
            work.
          schema:
            type: string
          example: cmp_kch12swdz9b7946003tht2zscx
        - name: function
          in: query
          description: >-
            Keeps the people in these functions, as a comma-separated list of
            `sales`, `cs` and `other`.
          schema:
            type: string
        - name: status
          in: query
          description: >-
            Keeps the people with these statuses, as a comma-separated list of
            `monitored`, `paused`, `pending` (shown as To validate in the app),
            `left` and `removed`. Defaults to every status except `removed`.
          schema:
            type: string
        - name: q
          in: query
          description: Searches people by name, ignoring case and accents.
          schema:
            type: string
        - name: limit
          description: The number of people per page, at most 200.
          in: query
          schema:
            type: integer
            default: 50
            maximum: 200
        - name: offset
          description: The number of people to skip, for paging.
          in: query
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: The people
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      people:
                        type: array
                        items:
                          $ref: '#/components/schemas/CompetitorTeamMember'
                      total:
                        type: integer
                      slot_usage:
                        $ref: '#/components/schemas/SlotUsage'
        '401':
          description: Invalid or missing API key
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
  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.