GET /v1/influencers/:influencerId

GET/v1/influencers/:influencerId

Phase 1stable

Auth: Bearer
Scope: influencers:write

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

influencerId
string (uuid)required
The influencer id.

Request

terminal

curl https://api.layers.com/v1/influencers/{influencerId} \
  -H "X-Api-Key: $LAYERS_API_KEY"

get-influencer.ts

const res = await fetch(
  `https://api.layers.com/v1/influencers/${influencerId}`,
  { headers: { 'X-Api-Key': process.env.LAYERS_API_KEY! } },
);
const influencer = await res.json();

get_influencer.py

import os, httpx

r = httpx.get(
    f"https://api.layers.com/v1/influencers/{influencer_id}",
    headers={"X-Api-Key": os.environ["LAYERS_API_KEY"]},
)
influencer = r.json()

Responses

200Full influencer record.

{
  "influencerId": "inf_01HXZ9...",
  "projectId": "proj_01HX...",
  "name": "Ava Chen",
  "gender": "female",
  "ageRange": "25-34",
  "ethnicity": null,
  "bodyType": null,
  "hairColor": null,
  "hairStyle": null,
  "style": "minimalist streetwear",
  "vibe": "warm and curious",
  "voiceDescription": null,
  "personality": {
    "traits": ["curious", "warm", "direct"],
    "tone": "conversational",
    "humor": "dry"
  },
  "referenceImages": [
    {
      "assetId": "asset_01HXZ9...",
      "url": "https://media.layers.com/.../ava-01.jpg",
      "thumbnailUrl": "https://media.layers.com/.../ava-01-thumb.jpg",
      "addedAt": "2026-04-01T14:22:10Z"
    }
  ],
  "status": "ready",
  "createdAt": "2026-04-01T14:22:10Z",
  "updatedAt": "2026-04-10T09:00:00Z"
}

404Influencer not in this org, or soft-deleted.

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Influencer not found.",
    "requestId": "req_..."
  }
}

Field semantics

status — draft | pending | training | ready | failed. Only ready influencers are usable for content generation without the workflow blocking.
gender — male | female | nonbinary | unspecified (or null if never set).
referenceImages[] — array of objects with {assetId, url, thumbnailUrl, addedAt}. Populated by the create job and POST /v1/influencers/:influencerId/reference-images.
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 partner API.

Errors

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