# GET /v1/projects/:projectId/influencers (/docs/api/reference/influencers/list-influencers)



<Endpoint method="GET" path="/v1/projects/:projectId/influencers" scope="influencers:write" phase="1" />

Returns influencers for the project, newest first. Soft-deleted (archived) influencers are excluded; there is no `includeArchived` flag. Results are cursor-paginated.

## Path parameters [#path-parameters]

<Parameters
  rows="[
  { name: 'projectId', type: 'string (uuid)', required: true, description: 'The project to list influencers for.' },
]"
/>

## Query parameters [#query-parameters]

<Parameters
  rows="[
  { name: 'cursor', type: 'string', description: 'Opaque cursor from the previous page.' },
  { name: 'limit', type: 'integer', default: '25', description: 'Page size, 1-100.' },
  { name: 'status', type: 'string', description: 'Filter by status.', enum: ['draft', 'pending', 'training', 'ready', 'failed'] },
]"
/>

## Request [#request]

<Tabs items="['curl', 'TypeScript', 'Python']">
  <Tab value="curl">
    ```sh title="terminal"
    curl "https://api.layers.com/v1/projects/{projectId}/influencers?limit=25" \
      -H "X-Api-Key: $LAYERS_API_KEY"
    ```
  </Tab>

  <Tab value="TypeScript">
    ```ts title="list-influencers.ts"
    const res = await fetch(
      `https://api.layers.com/v1/projects/${projectId}/influencers?limit=25`,
      { headers: { 'X-Api-Key': process.env.LAYERS_API_KEY! } },
    );
    const { items, nextCursor } = await res.json();
    ```
  </Tab>

  <Tab value="Python">
    ```py title="list_influencers.py"
    import os, httpx

    r = httpx.get(
        f"https://api.layers.com/v1/projects/{project_id}/influencers",
        params={"limit": 25},
        headers={"X-Api-Key": os.environ["LAYERS_API_KEY"]},
    )
    data = r.json()
    ```
  </Tab>
</Tabs>

## Responses [#responses]

<Response status="200" description="Page of influencer list items.">
  ```json
  {
    "items": [
      {
        "influencerId": "inf_01HXZ9...",
        "name": "Ava Chen",
        "gender": "female",
        "ageRange": "25-34",
        "status": "ready",
        "thumbnailUrl": "https://media.layers.com/.../ava-thumb.jpg",
        "createdAt": "2026-04-01T14:22:10Z"
      }
    ],
    "nextCursor": null
  }
  ```
</Response>

<Response status="404" description="Project not found or not visible to this key.">
  ```json
  {
    "error": {
      "code": "NOT_FOUND",
      "message": "Project not found.",
      "requestId": "req_..."
    }
  }
  ```
</Response>

## Notes [#notes]

* **List-item shape is slim.** It includes `influencerId, name, gender, ageRange, status, thumbnailUrl, createdAt`. For full identity fields (personality, style, reference images), fetch [`GET /v1/influencers/:influencerId`](/docs/api/reference/influencers/get-influencer).
* **Soft-deleted rows are hidden.** There is no flag to include them — delete is effectively terminal from the partner surface.

## Errors [#errors]

| Code              | When                                    |
| ----------------- | --------------------------------------- |
| `UNAUTHENTICATED` | Missing or invalid API key.             |
| `FORBIDDEN_SCOPE` | Key lacks `influencers:write`.          |
| `NOT_FOUND`       | Project id doesn't belong to this org.  |
| `VALIDATION`      | Invalid `limit`, `cursor`, or `status`. |

## See also [#see-also]

* [Create an influencer](/docs/api/reference/influencers/create-influencer)
* [Read one influencer](/docs/api/reference/influencers/get-influencer)
* [Generate content with an influencer](/docs/api/reference/content/generate-content)