# GET /v1/influencers/:influencerId (/docs/api/reference/influencers/get-influencer)



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

Returns the full influencer record. Influencer ids are globally unique - the path is not nested under a project. Access is gated by the influencer's project belonging to your org; cross-org reads collapse to `404 NOT_FOUND`.

## Path parameters [#path-parameters]

<Parameters
  rows="[
  { name: 'influencerId', type: 'string (uuid)', required: true, description: 'The influencer id.' },
]"
/>

## Request [#request]

<Tabs items="['curl', 'TypeScript', 'Python']">
  <Tab value="curl">
    ```sh title="terminal"
    curl https://api.layers.com/v1/influencers/{influencerId} \
      -H "Authorization: Bearer $LAYERS_API_KEY"
    ```
  </Tab>

  <Tab value="TypeScript">
    ```ts title="get-influencer.ts"
    const res = await fetch(
      `https://api.layers.com/v1/influencers/${influencerId}`,
      { headers: { 'Authorization': `Bearer ${process.env.LAYERS_API_KEY}` } },
    );
    const influencer = await res.json();
    ```
  </Tab>

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

    r = httpx.get(
        f"https://api.layers.com/v1/influencers/{influencer_id}",
        headers={"Authorization": f"Bearer {os.environ[\'LAYERS_API_KEY\']}"},
    )
    influencer = r.json()
    ```
  </Tab>
</Tabs>

## Responses [#responses]

<Response status="200" description="Full influencer record.">
  ```json
  {
    "influencerId": "inf_4a8e1bc2...",
    "projectId": "prj_9e2dca1f...",
    "name": "Ava Chen",
    "imageUrl": "https://media.layers.com/.../ava.png",
    "gender": "female",
    "ageRange": "young_adult",
    "brandVoice": "casual",
    "language": "en",
    "status": "ready",
    "errorMessage": null,
    "createdAt": "2026-04-01T14:22:10Z",
    "updatedAt": "2026-04-10T09:00:00Z"
  }
  ```
</Response>

<Response status="404" description="Influencer not in this org, or soft-deleted.">
  ```json
  {
    "error": {
      "code": "NOT_FOUND",
      "message": "Influencer not found.",
      "requestId": "req_..."
    }
  }
  ```
</Response>

## Field semantics [#field-semantics]

* **`status`** - `pending` | `training` | `ready` | `failed`. Only `ready` influencers are usable for content generation without waiting.
* **`imageUrl`** - URL of the generated face image (the primary artifact of the create-influencer workflow). `null` until `status === 'ready'`. Always a permanent CDN URL — no expiration, safe to cache or hotlink.
* **`gender`** - `male` | `female` | `non_binary`. Never null — content generation requires a gender mapping, so the column carries a real value (server default: `female`). Partners that omit `gender` on create get the project's `targetGender` if usable, else `female`.
* **`ageRange`** - `teen` | `young_adult` | `adult` | `mid_adult` | `mature` | `senior`. Never null — content generation reads this to pick persona presets, so every row carries a real value (server default: `young_adult` when omitted on create; auto-created influencers inherit from the project's target audience).
* **`brandVoice`** - `authentic` | `witty` | `professional` | `warm` | `casual` | `educational`. Drives tone in generated captions, hooks, and engagement comments. Defaults to `authentic` for influencers created without an explicit value. Influencers are the source of truth for voice — there's no per-content override.
* **`language`** - BCP 47 locale tag (`en`, `en-US`, `pt-BR`, `zh-Hans-CN`). Defaults to `en`. To run the same character in multiple languages, [clone the influencer](/docs/api/reference/influencers/clone-influencer) with a different `language` rather than swapping it per piece of content.
* **`errorMessage`** - Populated only when `status === 'failed'`; explains why the create workflow failed (Gemini quota, content-policy block, transient infra). `null` on every other status.
* **Soft-deleted influencers return 404.** DELETE flips `is_archived`; they disappear from GET as well as list. There is no way to retrieve a deleted influencer via the API integration.

## Errors [#errors]

| Code              | When                                 |
| ----------------- | ------------------------------------ |
| `NOT_FOUND`       | Id not in this org, or soft-deleted. |
| `FORBIDDEN_SCOPE` | Key lacks `influencers:write`.       |

## See also [#see-also]

* [List influencers](/docs/api/reference/influencers/list-influencers)
* [Patch an influencer](/docs/api/reference/influencers/patch-influencer)
* [Delete an influencer](/docs/api/reference/influencers/delete-influencer)