---
title: "Run an instance import"
method: POST
path: "/cloud/import"
tags: ["migration"]
---

# Run an instance import

`POST /cloud/import`

## Request

- Base URL: `https://eu.bisibility.com/api/v1`
- URL: `https://eu.bisibility.com/api/v1/cloud/import`
- Auth: HTTP bearer

Requires a migration token.

## Headers

- `Bisibility-API-Version` 'v1'
- `X-Bisibility-Source` 'sdk' | 'cli' | 'mcp'

## Request body

- CloudImportPackage
  - `keywords` CloudImportKeyword[], required
    - `device` 'desktop' | 'mobile', required
    - `id` string, required
    - `keyword` string, required
    - `location` string, required: Human-readable source location label. Version 7 identifies the location by location_key.
    - `location_key` string: Canonical source Location key. Required by version 7 exports.
    - `rankingHistory` CloudImportRankingHistory[]
      - `checkedAt` string, date-time, required
      - `normalizationVersion` 'v1' | 'v2', required
      - `position` integer, nullable, required
      - `previousPosition` integer, nullable, required
      - `provider` string, required
      - `rankingUrl` string, nullable, required: Absolute URL, path, null, or omitted.
      - `requestedDepth` 10 | 20 | 50 | 100, nullable, required
    - `tags` string[]
    - `target_url` string, nullable: Absolute URL, path, null, or omitted.
  - `project_id` string, required
  - `scope` 'current' | 'history'
  - `alert_rules` CloudImportAlertRule[], required
    - `change_pct` number, nullable
    - `channels` string[]: Delivery channels for alert notifications. Slack tenant delivery is available as an API-only preview. Workspace installation and channel management are not yet exposed in the dashboard. Push sends to the iOS devices that project members registered through /me/push-tokens; alerts from scheduled checks arrive as one summary push per rule. Every fired alert also creates an in-app notification, with or without channels.
    - `competitor_domain` string, nullable
    - `condition_type` 'change_pct' | 'competitor_overtake' | 'ctr_drop' | 'downtrend' | 'enters_top_n' | 'exits_top_n' | 'position_drop' | 'serp_feature' | 'threshold' | 'url_mismatch'
    - `drop_positions` integer, nullable
    - `enabled` boolean
    - `id` string, required
    - `name` string, required
    - `serp_feature` string, nullable
    - `severity` 'info' | 'warning' | 'urgent'
    - `target_type` 'all' | 'keyword' | 'tag'
    - `targets` CloudImportAlertRuleTarget[]
      - union
        - CloudImportKeywordAlertTarget
          - `device` 'desktop' | 'mobile'
          - `keyword` string
          - `keyword_id` string, required
          - `location` string: Human-readable source location label. Version 7 identifies the location by location_key.
          - `location_key` string: Canonical source Location key. Required by version 7 exports.
          - `type` 'keyword', required
        - CloudImportTagAlertTarget
          - `tag` string, required
          - `type` 'tag', required
    - `threshold_position` integer, nullable
    - `top_n` integer, nullable
  - `competitors` CloudImportCompetitor[], required
    - `domain` string, required: Canonical lowercase hostname without a scheme, path, www prefix, surrounding whitespace, or trailing dot.
    - `id` string, required
    - `label` string, nullable
  - `notification_preferences` CloudImportNotificationPreference[], required
    - `alert_email` boolean
    - `alert_in_app` boolean
    - `check_email` boolean
    - `check_in_app` boolean
    - `import_email` boolean
    - `import_in_app` boolean
    - `invite_email` boolean
    - `invite_in_app` boolean
    - `report_email` boolean
  - `saved_views` CloudImportSavedView[], required
    - `config` unknown
    - `id` string, required
    - `name` string, required
    - `surface` 'keywords' | 'competitors'
  - `exported_at` string, date-time
  - `version` 7 | 6 | 5, required: Version 7 exports require location_key. Version 6 and metadata-only version 5 remain import-compatible.

## Response `201`

Import completed

- CloudImportFinalizeResponse
  - `counts` CloudImportCounts, required
  - `job_id` string, required
  - `state` 'done', required

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `409`: Conflict; Unsupported API version
- `413`: Payload too large
- `419`: Migration token invalid or expired
- `423`: Project read-only
- `429`: Rate limited
- `500`: Import failed

## Changes

- **2026-10-19** `a6e1ec0dec82`: 1 breaking, 8 info
  - removed the media type `application/json` for the response with the status `409`
  - added the new `push` enum value to the request property `alert_rules/items/channels/items/`
  - media type `application/json` was changed to a more specific media type `application/problem+json` for the response status `400`
  - media type `application/json` was changed to a more specific media type `application/problem+json` for the response status `401`
  - …5 more

[Operation history](https://skmtc.dev/bisibility/apis/bisibility-public-api/changes/cloud/import/post.md)

---

[API](https://skmtc.dev/bisibility/apis/bisibility-public-api.md) · [All operations](https://skmtc.dev/bisibility/apis/bisibility-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bisibility/apis/bisibility-public-api/revisions/a6e1ec0dec82?raw)