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

> The people at a competitor whose LinkedIn activity Clustr watches

A competitor's Team: everyone Clustr tracks there, with the slot counter. The team search finds
the Sales and CS people when the competitor is added, and the monthly team refresh follows the
new joiners automatically while you have free slots; past your limit they are added Paused. You can [add someone](https://docs.clustr-ai.com/api-reference/add-competitor-team-member.md) it missed
and [remove someone](https://docs.clustr-ai.com/api-reference/remove-competitor-team-member.md) who should not be there.

Each row carries:

| Field | Column | Values |
| - | - | - |
| `full_name`, `avatar_url`, `linkedin_url` | Person | |
| `title` | Role | Their current title. |
| `function` | Function | `sales`, `cs` or `other`, from your [title list](https://docs.clustr-ai.com/api-reference/get-competitor-team-titles.md). |
| `status` | Status | `monitored` (takes a slot, activity collected), `paused` (Paused, no slot; `paused_reason` is `no_slot` or `manual`), `pending` (waiting for a decision; normally nobody, since joiners are followed automatically), `left` (Left the company, with `left_at` and `new_company_name`), `removed` (hidden by default). |
| `source` | Source | `search` (Auto extraction), `manual` or `employee_list` (Manual addition), `refresh` (Detected at refresh). |
| `monitored_since` | Added on | When they last became monitored. |
| `interactions_30d` | Interactions (30 d) | Retained interactions over the last 30 days. |

`function_changed_at` and `function_changed_title` flag someone whose title moved outside Sales and
CS: keep them with [Update Competitor Team Member](https://docs.clustr-ai.com/api-reference/update-competitor-team-member.md)
(`status: "monitored"`), or remove them.

The list comes ordered pending first (normally nobody), then Monitored, Paused and Left, each ranked founders and
executives first, then account managers and CSMs, AEs, BDRs and everyone else (`priority` 1 to 5).

```bash cURL theme={null}
curl https://api.clustr-ai.com/api/public/competitors/cmp_r0jpyyqyeh0txpgdhb604j2g9s/tracked-persons \
  -H "Authorization: Bearer YOUR_API_KEY"
```

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

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

```javascript JavaScript theme={null}
await fetch("https://api.clustr-ai.com/api/public/competitors/cmp_r0jpyyqyeh0txpgdhb604j2g9s/tracked-persons", {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});
```

```json 200 theme={null}
{
  "success": true,
  "data": {
    "tracked_persons": [
      {
        "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": "VP Sales",
        "headline": "VP Sales at Globex",
        "avatar_url": "https://media.licdn.com/dms/image/jane.jpg",
        "role_bucket": "exec",
        "priority": 1,
        "source": "search",
        "status": "monitored",
        "function": "sales",
        "monitored_since": "2026-09-02T09:00:00Z",
        "paused_reason": null,
        "function_changed_at": null,
        "interactions_30d": 14,
        "linkedin_url": "https://www.linkedin.com/in/jane-doe",
        "still_employed": true,
        "last_activity_at": "2026-10-01T14:20:00Z",
        "created_at": "2026-09-02T09:00:00Z",
        "updated_at": "2026-10-01T14:20:00Z"
      }
    ],
    "slot_usage": { "used": 182, "total": 200, "paused": 12, "pending": 3, "plan": "l200", "active": 182, "limit": 200 }
  }
}
```


## OpenAPI

````yaml GET /competitors/{id}/tracked-persons
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:
    get:
      tags:
        - Competitor Monitoring
      summary: List Competitor Team
      description: >
        The competitor's Team with every field: name, title, function, status

        (monitored, paused, to validate, left), source, added on
        (`monitored_since`) and

        interactions over 30 days, plus the slot counter. People you removed are
        listed

        when you send `include_excluded=1` or `status=removed`.
      operationId: listCompetitorTeam
      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_p4sq8pt49tetkec0dmpv2wycp7
        - name: include_excluded
          in: query
          description: >-
            `1` also lists the people removed from the Team. They carry
            `excluded_at` and `status: "removed"`.
          schema:
            type: string
            enum:
              - '0'
              - '1'
        - name: status
          in: query
          description: >-
            Comma-separated statuses to keep: `monitored`, `paused`, `pending`,
            `left`, `removed`. By

            default, every status except `removed`.
          schema:
            type: string
      responses:
        '200':
          description: The Team
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      tracked_persons:
                        type: array
                        items:
                          $ref: '#/components/schemas/CompetitorTeamMember'
                      slot_usage:
                        $ref: '#/components/schemas/SlotUsage'
        '401':
          description: Invalid or missing API key
        '403':
          description: Competitor monitoring is not enabled for this workspace
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Competitor not found
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.