# creators

Query

List and paginate creators for the current workspace, ordered newest first.

Available to agents as MCP tool `searchCreators` — see [Read tools](/api/v2/docs/mcp/read-tools#search-creators).

## Arguments

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `after` | `String` | No | `null` | Cursor for fetching the next page of results. |
| `customAttributeConditions` | [`[CustomAttributeConditionInput!]`](/api/v2/docs/types/custom-attribute-condition-input) | No | `[]` | Creator custom attributes conditions |
| `filter` | [`CreatorFilterInput`](/api/v2/docs/types/creator-filter-input) | No | `{}` | Filter criteria to narrow down results (e.g. by campaign roster or canonical location). |
| `first` | `Int` | No | `20` | Number of creators to return (page size). |
| `presetId` | `ID` | No | `null` | Saved Creator View ID. When provided, inline `filter` and `customAttributeConditions` are ignored; the view's stored conditions and sortBy drive the result set. The view's stored `filters` blob is not applied; a view whose only narrowing lives in `filters` returns the whole workspace. Accepts IDs returned by `creatorViews` / `creatorView` (workspace Creator Views, generally available), or by `campaignCreatorViews(campaignId:)` / `campaignCreatorView(id:)` (campaign-scoped, in alpha; opt in with the `campaign_creator_views` header). Non-Creator-View IDs raise a GraphQL error with `extensions.code = "WRONG_VIEW_TYPE"`; cross-shop or unknown IDs raise with `extensions.code = "NOT_FOUND"`. |

## Returns

A paginated connection of [`Creator`](/api/v2/docs/types/creator) nodes. See [Pagination](/api/v2/docs/types/pagination) for the connection shape.

## Examples

### List creators

Paginate the workspace's creators with their social profiles.

```graphql
query CreatorsDefault($first: Int, $after: String) {
  creators(first: $first, after: $after) {
    totalCount
    edges {
      node {
        id
        customAttributes
        socialProfiles {
          accountName
          provider
          followers
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

Variables:

```json
{
  "first": 10
}
```

Response — HTTP 200:

```json
{
  "data": {
    "creators": {
      "totalCount": 10,
      "edges": [
        {
          "node": {
            "id": "5e6f95ca-070b-5cef-8e0c-08d855365419",
            "customAttributes": {
              "age": null,
              "emails": [],
              "gender": "45b18b20-e86d-5c85-831c-19ada8104b25",
              "location": "United States",
              "full_name": null,
              "phone_numbers": []
            },
            "socialProfiles": [
              {
                "accountName": "northwind_creator_9",
                "provider": "INSTAGRAM",
                "followers": 41500
              }
            ]
          }
        },
        {
          "node": {
            "id": "7750875f-6037-5751-a493-86ac5fc3e9c9",
            "customAttributes": {
              "age": null,
              "emails": [],
              "gender": "52e6750a-79ca-5f7e-9352-228c7b9cb18f",
              "location": "United States",
              "full_name": null,
              "phone_numbers": []
            },
            "socialProfiles": [
              {
                "accountName": "northwind_creator_8",
                "provider": "YOUTUBE",
                "followers": 38000
              }
            ]
          }
        },
        {
          "node": {
            "id": "75fd5375-7f33-5331-a6cf-86e0c697c6f6",
            "customAttributes": {
              "age": null,
              "emails": [],
              "gender": "45b18b20-e86d-5c85-831c-19ada8104b25",
              "location": "United States",
              "full_name": null,
              "phone_numbers": []
            },
            "socialProfiles": [
              {
                "accountName": "northwind_creator_7",
                "provider": "TIKTOK",
                "followers": 34500
              }
            ]
          }
        },
        {
          "node": {
            "id": "ffe08e5e-e2f7-5dc3-813c-8b47d419f486",
            "customAttributes": {
              "age": null,
              "emails": [],
              "gender": "52e6750a-79ca-5f7e-9352-228c7b9cb18f",
              "location": "United States",
              "full_name": null,
              "phone_numbers": []
            },
            "socialProfiles": [
              {
                "accountName": "northwind_creator_6",
                "provider": "INSTAGRAM",
                "followers": 31000
              }
            ]
          }
        },
        {
          "node": {
            "id": "4fe7f884-6b21-5046-b965-b05e5b3aa957",
            "customAttributes": {
              "age": null,
              "emails": [],
              "gender": "45b18b20-e86d-5c85-831c-19ada8104b25",
              "location": "United States",
              "full_name": null,
              "phone_numbers": []
            },
            "socialProfiles": [
              {
                "accountName": "northwind_creator_5",
                "provider": "YOUTUBE",
                "followers": 27500
              }
            ]
          }
        },
        {
          "node": {
            "id": "3c132758-248e-542b-9219-dd949ad0f90e",
            "customAttributes": {
              "age": null,
              "emails": [],
              "gender": "52e6750a-79ca-5f7e-9352-228c7b9cb18f",
              "location": "Northwind HQ 4",
              "full_name": null,
              "phone_numbers": []
            },
            "socialProfiles": [
              {
                "accountName": "northwind_creator_4",
                "provider": "TIKTOK",
                "followers": 24000
              }
            ]
          }
        },
        {
          "node": {
            "id": "3d20f735-5ff1-5756-af1b-ff3a7315265b",
            "customAttributes": {
              "age": null,
              "emails": [],
              "gender": "45b18b20-e86d-5c85-831c-19ada8104b25",
              "location": "Northwind HQ 3",
              "full_name": null,
              "phone_numbers": []
            },
            "socialProfiles": [
              {
                "accountName": "northwind_creator_3",
                "provider": "INSTAGRAM",
                "followers": 20500
              }
            ]
          }
        },
        {
          "node": {
            "id": "13d02f43-65cb-55fb-a558-a89100226d58",
            "customAttributes": {
              "age": null,
              "emails": [],
              "gender": "52e6750a-79ca-5f7e-9352-228c7b9cb18f",
              "location": "Northwind HQ 2",
              "full_name": null,
              "phone_numbers": []
            },
            "socialProfiles": [
              {
                "accountName": "northwind_creator_2",
                "provider": "YOUTUBE",
                "followers": 17000
              }
            ]
          }
        },
        {
          "node": {
            "id": "c36d2c62-26da-5c7b-b198-b8f028209c4f",
            "customAttributes": {
              "age": null,
              "emails": [],
              "gender": "45b18b20-e86d-5c85-831c-19ada8104b25",
              "location": "Northwind HQ 1",
              "full_name": null,
              "phone_numbers": []
            },
            "socialProfiles": [
              {
                "accountName": "northwind_creator_1",
                "provider": "TIKTOK",
                "followers": 13500
              }
            ]
          }
        },
        {
          "node": {
            "id": "01f0f8f3-97dd-597c-8cc1-cf75eaabddb0",
            "customAttributes": {
              "age": null,
              "emails": [],
              "gender": "52e6750a-79ca-5f7e-9352-228c7b9cb18f",
              "location": "Northwind HQ 0",
              "full_name": null,
              "phone_numbers": []
            },
            "socialProfiles": [
              {
                "accountName": "northwind_creator_0",
                "provider": "INSTAGRAM",
                "followers": 10000
              }
            ]
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": false,
        "endCursor": "Z2lkOi8vYXJjaGl2ZS9DcmVhdG9yLzAxZjBmOGYzLTk3ZGQtNTk3Yy04Y2MxLWNmNzVlYWFiZGRiMA=="
      }
    }
  }
}
```

### Filter creators by custom attribute

Return creators whose location custom attribute contains a value.

```graphql
query CreatorsCustomAttributeCondition($customAttributeConditions: [CustomAttributeConditionInput!], $first: Int) {
  creators(customAttributeConditions: $customAttributeConditions, first: $first) {
    totalCount
    edges {
      node {
        id
        customAttributes
      }
    }
  }
}
```

Variables:

```json
{
  "customAttributeConditions": [
    {
      "field": "location",
      "operator": "CONTAINS",
      "type": "TEXT",
      "value": "Northwind HQ"
    }
  ],
  "first": 20
}
```

Response — HTTP 200:

```json
{
  "data": {
    "creators": {
      "totalCount": 5,
      "edges": [
        {
          "node": {
            "id": "3c132758-248e-542b-9219-dd949ad0f90e",
            "customAttributes": {
              "age": null,
              "emails": [],
              "gender": "52e6750a-79ca-5f7e-9352-228c7b9cb18f",
              "location": "Northwind HQ 4",
              "full_name": null,
              "phone_numbers": []
            }
          }
        },
        {
          "node": {
            "id": "3d20f735-5ff1-5756-af1b-ff3a7315265b",
            "customAttributes": {
              "age": null,
              "emails": [],
              "gender": "45b18b20-e86d-5c85-831c-19ada8104b25",
              "location": "Northwind HQ 3",
              "full_name": null,
              "phone_numbers": []
            }
          }
        },
        {
          "node": {
            "id": "13d02f43-65cb-55fb-a558-a89100226d58",
            "customAttributes": {
              "age": null,
              "emails": [],
              "gender": "52e6750a-79ca-5f7e-9352-228c7b9cb18f",
              "location": "Northwind HQ 2",
              "full_name": null,
              "phone_numbers": []
            }
          }
        },
        {
          "node": {
            "id": "c36d2c62-26da-5c7b-b198-b8f028209c4f",
            "customAttributes": {
              "age": null,
              "emails": [],
              "gender": "45b18b20-e86d-5c85-831c-19ada8104b25",
              "location": "Northwind HQ 1",
              "full_name": null,
              "phone_numbers": []
            }
          }
        },
        {
          "node": {
            "id": "01f0f8f3-97dd-597c-8cc1-cf75eaabddb0",
            "customAttributes": {
              "age": null,
              "emails": [],
              "gender": "52e6750a-79ca-5f7e-9352-228c7b9cb18f",
              "location": "Northwind HQ 0",
              "full_name": null,
              "phone_numbers": []
            }
          }
        }
      ]
    }
  }
}
```