---
title: "import_backlinks"
method: POST
path: "/v1/discovery/imports"
---

# import_backlinks

`POST /v1/discovery/imports`

## Request

- Base URL: `https://app.agentlinkops.com`
- URL: `https://app.agentlinkops.com/v1/discovery/imports`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Remaining arguments go in a JSON object body. Supply idempotencyKey as the Idempotency-Key header on this resource route.

## Headers

- `Idempotency-Key` string: Caller-generated key reused only for retries of the same operation and arguments in this workspace.
- `X-Workspace-ID` string

## Request body

- object
  - `projectId` string, required: project ID from create/list.
  - `supplier` 'ahrefs' | 'google_search_console' | 'bing_webmaster_tools' | 'semrush' | 'majestic' | 'moz' | 'dataforseo' | 'linkody' | 'csv', required: Source of imported candidate evidence, retained as provenance.
  - `targetKind` 'domain' | 'exact_url', required: Whether target identifies an exact URL or a domain.
  - `target` string, required: Exact URL or domain to query, interpreted according to targetKind.
  - `includeSubdomains` boolean, required: Include subdomains of the selected domain in this query.
  - `backlinksStatus` 'live' | 'lost' | 'all', required: Supplier-reported backlink status filter; this is not AgentLinkOps verification.
  - `rows` union[], required: Each row requires source_url and target_url. The outer target defines the import scope. target_url names the destination. Checks match that URL exactly by default. For a source-only Google Search Console export, set target_basis=user_supplied_target_expectation. Set target_url to the confirmed site root URL for a domain import, or the selected URL for an exact URL import. For declared expectations, checks use the saved website scope or selected exact URL. Invalid rows return positional errors without rejecting valid neighbors. Example: {"source_url":"https://publisher.example/article","target_url":"https://example.com/","anchor":"Example"}.
    - union
      - unknown
      - object
        - `source_url` string, required
        - `target_url` string, required
        - `target_basis` 'supplier_observed' | 'user_supplied_target_expectation'
        - `anchor` string, nullable
        - `rel` union
          - string
          - string[]
        - `dofollow` boolean, nullable
        - `link_type` string, nullable
        - `first_seen` string, nullable
        - `last_seen` string, nullable
        - `is_lost` boolean, nullable
        - `supplier_row_id` string, nullable
        - `supplier_metrics` object, nullable
  - `supplierGeneratedAt` string, date-time, nullable: Supplier export generation timestamp, distinct from import time.

## Response `201`

Remaining arguments go in a JSON object body. Supply idempotencyKey as the Idempotency-Key header on this resource route.

- object
  - `v` 1, required
  - `id` string, required: Resource identifier returned by the operation.
  - `workspace_id` string, required: Workspace that owns this record.
  - `project_id` string, required: Project that owns this record.
  - `provider` 'linktrail_corpus' | 'dataforseo' | 'imported', required
  - `data_mode` 'synthetic' | 'owned_corpus' | 'provider_index' | 'imported', required
  - `query` object, required
    - `target_kind` 'domain' | 'exact_url', required
    - `target` string, required
    - `include_subdomains` boolean, required
    - `backlinks_status_type` 'live' | 'lost' | 'all', required
    - `exclude_internal_backlinks` boolean, required
    - `mode` 'as_is', required
    - `filters` unknown, required
    - `rank_scale` 'one_thousand', nullable, required
    - `page_limit` integer, required
    - `row_limit` integer, required
  - `status` 'queued' | 'running' | 'succeeded' | 'partial' | 'failed' | 'reconciliation_required', required: Resource lifecycle status.
  - `created_at` string, date-time, required: UTC timestamp when the record was created.
  - `started_at` string, date-time, nullable, required
  - `finished_at` string, date-time, nullable, required
  - `coverage` 'pending' | 'complete_for_query' | 'capped' | 'partial' | 'unknown', required: Dataset scope and completeness, including limits on what these results establish.
  - `coverage_reason` string, nullable, required
  - `provider_total_count` integer, nullable, required
  - `usage` object, required
    - `unit` 'discovery', required
    - `currency` 'USD', required
    - `quote_id` string, required
    - `max_cost_microusd` integer, required
    - `reserved_cost_microusd` integer, required
    - `provider_reported_cost_microusd` integer, nullable, required
    - `request_count` integer, required
    - `returned_rows` integer, required
    - `accepted_candidates` integer, required
    - `rejected_rows` integer, required
    - `duplicate_rows` integer, required
  - `operation` 'backlinks', required
  - `coverage_scope` 'customer_import' | 'corpus_subset' | 'provider_query', required
  - `whole_web_coverage` false, required: False: these results do not measure the whole web.
  - `replayed` boolean: True when the response reuses an earlier request with the same idempotency value.
  - `admission` object, nullable
    - `operation_id` string, required
    - `project_id` string, required: Project that owns this record.
    - `context` 'import' | 'candidate' | 'candidate_batch' | 'serve', required
    - `decisions` object[], required
      - `index` integer, required
      - `url` string, required
      - `normalized_url` string, nullable, required
      - `host` string, nullable, required
      - `decision` 'admitted' | 'rejected', required
      - `reason` string, required: Recorded explanation; null when no explanation applies.
      - `rule_kind` string, nullable, required
      - `rule_id` string, nullable, required
      - `rule_value` string, nullable, required
      - `cap` object, nullable, required
        - `limit` integer, required
        - `used` integer, required
      - `subject_key` string, required
    - `summary` object, required: Grouped change counts included in this delivery, limited to accessible websites.
      - `total` integer, required
      - `admitted` integer, required
      - `rejected` integer, required
      - `by_rule` object, required
    - `policy_revision` integer, required
    - `disavow_revision` integer, required
    - `replayed` boolean, required: True when the response reuses an earlier request with the same idempotency value.
  - `rejected` object[], required
    - `row` number, required
    - `reason` string, required: Recorded explanation; null when no explanation applies.
    - `admission` object
      - `index` integer, required
      - `url` string, required
      - `normalized_url` string, nullable, required
      - `host` string, nullable, required
      - `decision` 'admitted' | 'rejected', required
      - `reason` string, required: Recorded explanation; null when no explanation applies.
      - `rule_kind` string, nullable, required
      - `rule_id` string, nullable, required
      - `rule_value` string, nullable, required
      - `cap` object, nullable, required
        - `limit` integer, required
        - `used` integer, required
      - `subject_key` string, required
  - `duplicates` object[], required
    - `row` number, required
    - `first_seen_on_row` number, required
  - `rejected_total` number, required
  - `duplicates_total` number, required

## Other responses

- `429`: Request-rate or usage refusal. Inspect error.code and recovery details before retrying.
- `default`: Error envelope. Non-configuration 5xx messages are masked and details omitted; allowlisted configuration errors retain static operator recovery.

---

[API](https://skmtc.dev/agentlinkops/apis/agentlinkops-http-api.md) · [All operations](https://skmtc.dev/agentlinkops/apis/agentlinkops-http-api/llms.txt) · [OpenAPI document](https://skmtc.dev/agentlinkops/apis/agentlinkops-http-api/revisions/1bf30c2912b2?raw)