Skip to Content
API ReferenceCreators

Creators

Reminder: All queries on this page require the WORKSPACE-ID header. See Getting Started for setup.

A Creator represents a person — an influencer or content creator your brand is working with. Each creator has a profile in your workspace CRM with custom attributes (name, email, location, labels, etc.) and can have multiple social accounts linked to them across platforms.

Via the API, you can query creators by name, email, location, label, or any other attribute. This is the same data you see in the Creators page  in the Archive UI.

Important: The API only returns creators already in your workspace CRM. It does not provide access to the Creator Search database (the global discovery tool).

Creators vs. Social Profiles

Learn more: Difference Between Creators and Social Profiles 

Object
Creator
A person in your CRM
creatorscreator
Hierarchy
Parent
Custom attributes
full_namelocationemailsphone_numberslabelsgenderagecollaboration_statusfavouritenotescategory
Example
→ Sarah = 1 creator
Use when
Looking up CRM data, filtering by attributes
1 → many
Object
Social Profile
A platform account
socialProfile
Hierarchy
Child — belongs to one creator
Platforms
InstagramTikTokYouTube
Platform data
accountNamefullNamefollowersfollowingverifiedproAccountprivateavataroriginalUrlemailphoneNumbers
Example
→ Sarah's Instagram + Sarah's TikTok = 2 social profiles
Use when
Looking up platform stats by handle
Quick rule: If you need CRM-level data — name, email, labels, relationship status — query the creator. If you need platform stats for a specific handle — followers, verified status — query the socialProfile. Every Social Profile carries a reference back to its Creator.

To look up a specific social account by handle, see the Social Profiles page.

All Creator fields

FieldTypeDescription
idIDUnique creator identifier
customAttributesJSONAll CRM attributes: full_name, location, emails, phone_numbers, labels, gender, age, collaboration_status (Relationship Status), favourite, notes, category. Note: phone_numbers here is manually entered in Archive — it may differ from phoneNumbers on the creator’s Social Profile, which is pulled from the platform.
socialProfilesArrayAll social profiles linked to this creator — see Social Profiles for the full list of profile fields

SELECT fields like gender, age, and labels return UUIDs, not readable names. Use customAttributeSchemas(entity: CREATOR) to map UUIDs to labels. See Custom Attributes.

Creator queries

List creators in your workspace

The first parameter defaults to 20 if not specified. To get more results, set first up to a maximum of 100, or use pagination to fetch additional pages.

query ListCreators {
  creators(first: 20) {
    nodes {
      id
      customAttributes
      socialProfiles {
        accountName
        provider
        followers
        verified
      }
    }
    pageInfo { hasNextPage endCursor }
    totalCount
  }
}

Example response:

{
  "data": {
    "creators": {
      "totalCount": 1284,
      "pageInfo": { "hasNextPage": true, "endCursor": "eyJpZCI6Ii4uLiJ9" },
      "nodes": [
        {
          "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
          "customAttributes": {
            "full_name": "Laura Méndez",
            "location": "Miami, United States",
            "age": "82b05d3f-c262-40e7-bdcb-6544496f978d",
            "gender": "17a79434-ed12-46d7-9aea-33806bfa1725",
            "emails": ["contact@lauramendez.com"],
            "phone_numbers": ["+1 305 555 0100"],
            "labels": [],
            "collaboration_status": "840bfa06-e02d-4083-af43-c3b9777fffcc",
            "favourite": false,
            "notes": "Top performer Q1 2026",
            "category": []
          },
          "socialProfiles": [
            { "accountName": "lauramendez", "provider": "INSTAGRAM", "followers": 312000, "verified": false },
            { "accountName": "lauramendez.style", "provider": "TIKTOK", "followers": 890000, "verified": false }
          ]
        },
        "... 19 more creators"
      ]
    }
  }
}

Note: SELECT fields like age and gender return internal option IDs (UUIDs), not readable labels. See Custom Attributes to learn how to map them.

Using with AI:

“Show me all creators in my workspace with their social profiles and follower counts” “How many creators do I have in total?”

Search creator by name

query CreatorByName {
  creators(
    first: 5
    customAttributeConditions: [
      { field: "full_name", operator: CONTAINS, type: TEXT, value: "Laura" }
    ]
  ) {
    totalCount
    nodes {
      id
      customAttributes
      socialProfiles { accountName provider followers }
    }
  }
}

Example response:

{
  "data": {
    "creators": {
      "totalCount": 2,
      "nodes": [
        {
          "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
          "customAttributes": {
            "full_name": "Laura Méndez",
            "location": "Miami, United States"
          },
          "socialProfiles": [
            { "accountName": "lauramendez", "provider": "INSTAGRAM", "followers": 312000 }
          ]
        }
      ]
    }
  }
}

Using with AI:

“Find the creator named Laura” “Search for a creator whose name contains Méndez”

Search creator by email

query CreatorByEmail {
  creators(
    first: 5
    customAttributeConditions: [
      { field: "emails", operator: CONTAINS, type: TEXT, value: "lauramendez" }
    ]
  ) {
    totalCount
    nodes {
      id
      customAttributes
      socialProfiles { accountName provider }
    }
  }
}

Example response:

{
  "data": {
    "creators": {
      "totalCount": 1,
      "nodes": [
        {
          "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
          "customAttributes": {
            "full_name": "Laura Méndez",
            "emails": ["contact@lauramendez.com"]
          },
          "socialProfiles": [
            { "accountName": "lauramendez", "provider": "INSTAGRAM" }
          ]
        }
      ]
    }
  }
}

Note: Even though emails is a TEXT_LIST field in the schema, use type: TEXT with operator: CONTAINS to search within the list.

Using with AI:

“Find the creator with email contact@lauramendez.com” “Search for a creator by email”

Search creator by location

query CreatorsByLocation {
  creators(
    first: 20
    customAttributeConditions: [
      { field: "location", operator: CONTAINS, type: TEXT, value: "United States" }
    ]
  ) {
    totalCount
    nodes {
      id
      customAttributes
      socialProfiles { accountName provider followers }
    }
  }
}

Example response:

{
  "data": {
    "creators": {
      "totalCount": 347,
      "nodes": [
        {
          "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
          "customAttributes": {
            "full_name": "Laura Méndez",
            "location": "Miami, United States"
          },
          "socialProfiles": [
            { "accountName": "lauramendez", "provider": "INSTAGRAM", "followers": 312000 }
          ]
        },
        "... 19 more creators"
      ]
    }
  }
}

Using with AI:

“Find all creators located in the United States” “Show me creators based in New York” “List all creators in the UK”

Search creator by label

Labels are custom tags you can apply to creators in the Archive UI. To filter by label, you need the label’s UUID — get it first from customAttributeSchemas:

query GetLabelSchemas {
  customAttributeSchemas(entity: CREATOR) {
    key
    name
    type
    options { id name }
  }
}

Find the entry with key: "labels" and copy the id of the label you want to filter by. Then:

query CreatorsByLabel {
  creators(
    first: 20
    customAttributeConditions: [
      { field: "labels", operator: CONTAINS, type: MULTIPLE_SELECT, value: "<label-uuid>" }
    ]
  ) {
    totalCount
    nodes {
      id
      customAttributes
      socialProfiles { accountName provider followers }
    }
  }
}

Example response:

{
  "data": {
    "creators": {
      "totalCount": 42,
      "nodes": [
        {
          "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
          "customAttributes": {
            "full_name": "Laura Méndez",
            "labels": ["8f1a2b3c-d4e5-6789-abcd-ef0123456789"]
          },
          "socialProfiles": [
            { "accountName": "lauramendez", "provider": "INSTAGRAM", "followers": 312000 }
          ]
        },
        "... 19 more creators"
      ]
    }
  }
}

Labels are stored as UUIDs in customAttributes.labels. Always run customAttributeSchemas first to map UUIDs to readable names. Label options are workspace-specific — the UUIDs will differ between workspaces.

Using with AI:

“Find all creators with the label ‘VIP’” “Show me creators tagged as ‘Gifted’” “List all creators that have any label assigned”

Get a single creator

query GetCreator {
  creator(id: "f1a2b3c4-d5e6-7890-abcd-ef1234567890") {
    id
    customAttributes
    socialProfiles {
      accountName
      provider
      followers
      verified
    }
  }
}

Example response:

{
  "data": {
    "creator": {
      "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "customAttributes": {
        "full_name": "Laura Méndez",
        "location": "Miami, United States",
        "emails": ["contact@lauramendez.com"],
        "phone_numbers": []
      },
      "socialProfiles": [
        { "accountName": "lauramendez", "provider": "INSTAGRAM", "followers": 312000, "verified": false },
        { "accountName": "lauramendez.style", "provider": "TIKTOK", "followers": 890000, "verified": false }
      ]
    }
  }
}

Using with AI:

“Get me the full profile for creator Laura Méndez” “Show me all social profiles linked to this creator”

Creator Views

Creator Views are the saved filters under Creators → Views in the Archive sidebar — a reusable slice of your creator CRM (e.g. “Contracted Talent”, “Female creators”). The API can list, create, edit, and delete them, and read the creators inside one via presetId.

Creator Views narrow by customAttributeConditions, not filters. This is the one way Creator Views differ from Content Views and Social Profile Views: a Creator View’s filters blob is stored and echoed back, but not applied when you read the view. creators(presetId:) narrows only by the view’s customAttributeConditions and sort. To build a view that actually filters, put your conditions in customAttributeConditions (same shape as Search creator by label) and leave filters as {}.

List Creator Views

query ListCreatorViews {
  creatorViews {
    id
    name
    customAttributeConditions
    sort
    showReportingStats
    group { id name }
  }
}

Example response:

{
  "data": {
    "creatorViews": [
      {
        "id": "c1d2e3f4-a5b6-7890-cdef-234567890123",
        "name": "Contracted Talent",
        "customAttributeConditions": [
          { "field": "collaboration_status", "operator": "is", "type": "single_select_v3", "value": "72850838-be63-42dd-b720-943dccc2d968" }
        ],
        "sort": [],
        "showReportingStats": true,
        "group": null
      }
    ]
  }
}

Using with AI:

“List my Creator Views”

Read creators from a view

Pass a view’s id as presetId to the creators query. The view’s customAttributeConditions are applied automatically — you don’t re-send them:

query CreatorsFromView {
  creators(presetId: "c1d2e3f4-a5b6-7890-cdef-234567890123", first: 20) {
    totalCount
    nodes {
      id
      customAttributes
      socialProfiles { accountName provider followers }
    }
  }
}

As with every presetId, adding customAttributeConditions or filter alongside it does not narrow further — only sorting composes with a preset. (Anything set on the view via filters is ignored entirely — see the note above.)

Using with AI:

“Show me the creators in my ‘Contracted Talent’ view”

Create a Creator View

createCreatorView saves a new view. name and filters are both required by the schema, but since filters is not applied on read, pass filters: {} and put your real narrowing in customAttributeConditions:

mutation CreateCreatorView {
  createCreatorView(input: {
    name: "Contracted Talent"
    filters: {}
    customAttributeConditions: [
      { field: "collaboration_status", operator: IS, type: SINGLE_SELECT_V3, value: "<option-uuid>" }
    ]
  }) {
    creatorView { id name customAttributeConditions }
    userErrors { field message }
  }
}

Get option UUIDs from customAttributeSchemas(entity: CREATOR) — see Search creator by label. The view appears in the Archive UI sidebar immediately, and its id works as presetId right away.

Using with AI:

“Save a Creator View for creators whose relationship status is Contracted”

Update a Creator View

updateCreatorView takes the view id as a top-level argument (not inside input). Partial updates are supported — omitted fields keep their current values, so renaming a view doesn’t require re-sending its conditions:

mutation RenameCreatorView {
  updateCreatorView(
    id: "c1d2e3f4-a5b6-7890-cdef-234567890123"
    input: { name: "Contracted Talent (2026)" }
  ) {
    creatorView { id name }
    userErrors { field message }
  }
}

Using with AI:

“Rename my ‘Contracted Talent’ Creator View to ‘Contracted 2026‘“

Delete a Creator View

mutation DeleteCreatorView {
  deleteCreatorView(id: "c1d2e3f4-a5b6-7890-cdef-234567890123") {
    deletedCreatorViewId
    userErrors { field message }
  }
}

Deleting a view never touches the creators themselves — it only removes the saved filter. deletedCreatorViewId echoes the id on success; deleting an already-deleted id returns null there (a safe no-op).

Using with AI:

“Delete my ‘Old Outreach’ Creator View”

To look up platform data (followers, verified status, etc.) for a specific social account, use the Social Profiles page.

Last updated on
Items (UGC)Social Profiles