# importCreators

Mutation

Import creators into the current workspace by social handle; returns an operationId to poll with `operation(id:)` and `operationRecords`.

Available to agents as MCP tool `importCreators` — see [Write tools](/api/v2/docs/mcp/write-tools#import-creators).

## Arguments

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `creators` | [`[CreatorImportInput!]!`](/api/v2/docs/types/creator-import-input) | Yes | — | The creators to import, 1 to 250. More than 250 refuses the whole request. |
| `operationId` | `ID` | No | — | Optional version 4 UUID to mint the operation with, so a retried request cannot start a second import: a repeat with the same id is refused with a userError on `operationId` and the first operation keeps running. Omit it to get a server-minted id. |

## Returns

| Name | Type | Description |
| --- | --- | --- |
| `acceptedCount` | `Int!` | Number of creators accepted into the import operation. |
| `operationId` | `ID` | ID of the background import operation. Poll `operation(id:)` and `operationRecords` with it. Null when every creator was skipped or the request was refused. |
| `skipped` | [`[ImportCreatorsSkippedRow!]!`](/api/v2/docs/types/import-creators-skipped-row) | Creators skipped instead of imported, with the reason for each. |
| `userErrors` | [`[UserError!]!`](/api/v2/docs/types/user-error) | Errors that refused the whole request: an empty or oversized `creators` list, a creator with too many handles, more than 20 labels or a label name over 100 characters, an `operationId` that is not a version 4 UUID or was already used, labels locked by another import (retry the request), or a workspace with no user to attribute the import to. A cap one creator breaks points at it: `field` is ["creators", "<index>", "handles"] or ["creators", "<index>", "labels"]. Empty on success. |

## Examples

### Import creators by handle

Start a background import of creators by their social handles, with a client-minted operationId.

```graphql
mutation ImportCreatorsDefault($creators: [CreatorImportInput!]!, $operationId: ID) {
  importCreators(creators: $creators, operationId: $operationId) {
    operationId
    acceptedCount
    skipped {
      index
      provider
      handle
      reason
    }
    userErrors {
      field
      message
    }
  }
}
```

Variables:

```json
{
  "creators": [
    {
      "handles": [
        {
          "provider": "INSTAGRAM",
          "handle": "@maya.greenhouse"
        },
        {
          "provider": "TIKTOK",
          "handle": "mayagreenhouse"
        }
      ],
      "labels": [
        "Q4 seeding"
      ]
    },
    {
      "handles": [
        {
          "provider": "YOUTUBE",
          "handle": "fernandfrondstudio"
        }
      ]
    },
    {
      "handles": [
        {
          "provider": "INSTAGRAM",
          "handle": "not a handle!"
        }
      ]
    }
  ],
  "operationId": "3f1c9a52-7d4e-4b8a-9c21-6e5f0a7b8d13"
}
```

Response — HTTP 200:

```json
{
  "data": {
    "importCreators": {
      "operationId": "3f1c9a52-7d4e-4b8a-9c21-6e5f0a7b8d13",
      "acceptedCount": 2,
      "skipped": [
        {
          "index": 2,
          "provider": "INSTAGRAM",
          "handle": "not a handle!",
          "reason": "INVALID_HANDLE"
        }
      ],
      "userErrors": []
    }
  }
}
```