> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentlinkops.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Import backlinks
> Store a backlink export the user already owns (Ahrefs, Search Console, Semrush, Majestic, Moz, DataForSEO, Linkody or generic CSV) as unverified discovery candidates.
`import_backlinks`
Store a backlink export the user already owns (Ahrefs, Search Console, Semrush, Majestic, Moz, DataForSEO, Linkody or generic CSV) as unverified discovery candidates. Buys nothing; the supplier and its dates stay in provenance, separate from any check we run. Never claims complete coverage. Rejected rows return by position, none dropped; re-importing the same rows returns the same run. Rows are not verified, not monitored and never enter a shared corpus.
Available in the deployed MCP and HTTP bundle. Confirm access and inputs with your connected catalog. Workspace scopes and enabled providers still apply.
| Access | Behavior |
| ----------------- | --------------------- |
| `discovery:write` | Writes or admits work |
This operation changes saved state. Review its inputs and retry behavior before calling.
## Example request
Connect through [MCP](/guides/connect-mcp), [CLI](/guides/connect-cli), or [HTTP](/guides/connect-http). Replace example identifiers with records from your workspace.
```json MCP theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "import_backlinks",
"arguments": {
"projectId": "project_example",
"supplier": "ahrefs",
"targetKind": "domain",
"target": "example.com",
"includeSubdomains": false,
"backlinksStatus": "live",
"rows": [
{
"source_url": "https://publisher.example.com/resources",
"target_url": "https://example.com/guide"
}
]
}
}
}
```
```bash CLI theme={null}
agentlinkops call import_backlinks --args '{"projectId":"project_example","supplier":"ahrefs","targetKind":"domain","target":"example.com","includeSubdomains":false,"backlinksStatus":"live","rows":[{"source_url":"https://publisher.example.com/resources","target_url":"https://example.com/guide"}]}'
```
```bash HTTP theme={null}
curl "$AGENTLINKOPS_API_URL/v1/commands/import_backlinks" \
-H "Authorization: Bearer $AGENTLINKOPS_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"projectId":"project_example","supplier":"ahrefs","targetKind":"domain","target":"example.com","includeSubdomains":false,"backlinksStatus":"live","rows":[{"source_url":"https://publisher.example.com/resources","target_url":"https://example.com/guide"}]}'
```
## Returned result
Illustrative data validated against the documented response schema. IDs and dates are examples, not a live account capture. MCP returns this data in `structuredContent` and in a text content block; generic HTTP and CLI return the JSON result directly.
```json theme={null}
{
"v": 1,
"id": "dr_import_example",
"workspace_id": "ws_example",
"project_id": "project_example",
"provider": "imported",
"data_mode": "imported",
"query": {
"target_kind": "domain",
"target": "example.com",
"include_subdomains": false,
"backlinks_status_type": "live",
"exclude_internal_backlinks": true,
"mode": "as_is",
"filters": null,
"order_by": [
"as_supplied"
],
"rank_scale": null,
"page_limit": 1,
"row_limit": 1
},
"status": "partial",
"created_at": "2026-09-13T12:00:00.000Z",
"started_at": "2026-09-13T12:00:00.000Z",
"finished_at": "2026-09-13T12:00:00.000Z",
"coverage": "partial",
"coverage_reason": "import_scope_unknown",
"provider_total_count": null,
"usage": {
"unit": "discovery",
"currency": "USD",
"quote_id": "import_example",
"max_cost_microusd": 0,
"reserved_cost_microusd": 0,
"provider_reported_cost_microusd": 0,
"request_count": 1,
"returned_rows": 1,
"accepted_candidates": 1,
"rejected_rows": 0,
"duplicate_rows": 0
},
"operation": "backlinks",
"coverage_scope": "customer_import",
"whole_web_coverage": false,
"replayed": false,
"rejected": [],
"duplicates": [],
"rejected_total": 0,
"duplicates_total": 0
}
```
## Input fields
Omit optional fields when you do not want to supply them. Null is accepted only where listed. Unknown input properties are rejected.
* **`projectId`** (string, required): Identifier of the project returned by its create or list operation. pattern: "^\[a-zA-Z0-9\_-]\{1,128}\$"
* **`supplier`** (string, required): Source of imported candidate evidence, retained as provenance. values: "ahrefs", "google\_search\_console", "bing\_webmaster\_tools", "semrush", "majestic", "moz", "dataforseo", "linkody", "csv"
* **`targetKind`** (string, required): Whether target identifies an exact URL or a domain. values: "domain", "exact\_url"
* **`target`** (string, required): Exact URL or domain to query, interpreted according to targetKind. minLength: 1; maxLength: 4096
* **`includeSubdomains`** (boolean, required): Include subdomains of the selected domain in this query.
* **`backlinksStatus`** (string, required): Supplier-reported backlink status filter; this is not AgentLinkOps verification. values: "live", "lost", "all"
* **`rows`** (array, required): Each row requires source\_url and target\_url. target\_url is the row destination; the outer target defines the import scope. Optional fields are shown in the row schema. Invalid rows return positional errors without rejecting valid neighbors. Example: \{"source\_url":"[https://publisher.example/article","target\_url":"https://example.com/","anchor":"Example"\}](https://publisher.example/article","target_url":"https://example.com/","anchor":"Example"\});. minItems: 1; maxItems: 1000
* **`supplierGeneratedAt`** (string / null, optional): Supplier export generation timestamp, distinct from import time. default: null
* **`idempotencyKey`** (string, optional): Caller-generated key reused only for retries of the same operation and arguments in this workspace. pattern: "^\[\x21-\x7e]\{1,200}\$"
| Field | Type | Presence | Meaning and constraints |
| ------------------------- | ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `projectId` | string | Required | Identifier of the project returned by its create or list operation. pattern: "^\[a-zA-Z0-9\_-]\{1,128}\$" |
| `supplier` | string | Required | Source of imported candidate evidence, retained as provenance. values: "ahrefs", "google\_search\_console", "bing\_webmaster\_tools", "semrush", "majestic", "moz", "dataforseo", "linkody", "csv" |
| `targetKind` | string | Required | Whether target identifies an exact URL or a domain. values: "domain", "exact\_url" |
| `target` | string | Required | Exact URL or domain to query, interpreted according to targetKind. minLength: 1; maxLength: 4096 |
| `includeSubdomains` | boolean | Required | Include subdomains of the selected domain in this query. |
| `backlinksStatus` | string | Required | Supplier-reported backlink status filter; this is not AgentLinkOps verification. values: "live", "lost", "all" |
| `rows` | array | Required | Each row requires source\_url and target\_url. target\_url is the row destination; the outer target defines the import scope. Optional fields are shown in the row schema. Invalid rows return positional errors without rejecting valid neighbors. Example: \{"source\_url":"[https://publisher.example/article","target\_url":"https://example.com/","anchor":"Example"\}](https://publisher.example/article","target_url":"https://example.com/","anchor":"Example"\});. minItems: 1; maxItems: 1000 |
| `rows[].source_url` | string | Required | maxLength: 4096 |
| `rows[].target_url` | string | Required | maxLength: 4096 |
| `rows[].anchor` | string / null | Optional | |
| `rows[].rel` | object / null | Optional | |
| `rows[].dofollow` | boolean,null | Optional | |
| `rows[].link_type` | string / null | Optional | |
| `rows[].first_seen` | string / null | Optional | |
| `rows[].last_seen` | string / null | Optional | |
| `rows[].is_lost` | boolean,null | Optional | |
| `rows[].supplier_row_id` | string / null | Optional | Identifier returned by the related operation. |
| `rows[].supplier_metrics` | object / null | Optional | |
| `supplierGeneratedAt` | string / null | Optional | Supplier export generation timestamp, distinct from import time. default: null |
| `idempotencyKey` | string | Optional | Caller-generated key reused only for retries of the same operation and arguments in this workspace. pattern: "^\[\x21-\x7e]\{1,200}\$" |
### Validation and omitted values
includeSubdomains and backlinksStatus are required import scope choices. Omitted supplierGeneratedAt remains null, rather than using the import date as a supplier date.
Omitted idempotencyKey uses deterministic content-based import identity. Re-importing the same scope, supplier and rows as supplied reuses the run. Imported order remains as\_supplied.
Every row requires source\_url and target\_url. Optional supplier metadata retains its provenance; invalid rows are returned with their positions while valid neighbors continue.
### Defaults when omitted
| Field | Default |
| --------------------- | ------- |
| `supplierGeneratedAt` | `null` |
## Output fields
Fields inside optional or nullable parents apply only when that parent exists. [Common schema conventions](/reference/schemas) explain evidence states, empty lists and extensions.
* **`v`** (number, required): must equal 1
* **`id`** (string, required): Resource identifier returned by the operation. minLength: 1; maxLength: 128; pattern: "^\[a-zA-Z0-9\_-]+\$"
* **`workspace_id`** (string, required): Workspace that owns this record. minLength: 1; maxLength: 128; pattern: "^\[a-zA-Z0-9\_-]+\$"
* **`project_id`** (string, required): Project that owns this record. minLength: 1; maxLength: 128; pattern: "^\[a-zA-Z0-9\_-]+\$"
* **`provider`** (string, required): values: "linktrail\_corpus", "dataforseo", "imported"
* **`data_mode`** (string, required): values: "synthetic", "owned\_corpus", "provider\_index", "imported"
* **`query`** (object, required): additional fields rejected
* **`status`** (string, required): Resource lifecycle status. values: "queued", "running", "succeeded", "partial", "failed", "reconciliation\_required"
* **`created_at`** (string, required): UTC timestamp when the record was created. format: "date-time"; pattern: "^(?:(?:\d\d\[2468]\[048]|\d\d\[13579]\[26]|\d\d0\[48]|\[02468]\[048]00|\[13579]\[26]00)-02-29|\d\{4}-(?:(?:0\[13578]|1\[02])-(?:0\[1-9]|\[12]\d|3\[01])|(?:0\[469]|11)-(?:0\[1-9]|\[12]\d|30)|(?:02)-(?:0\[1-9]|1\d|2\[0-8])))T(?:(?:\[01]\d|2\[0-3]):\[0-5]\d:\[0-5]\d\\.\d\{3}(?:Z))\$"
* **`started_at`** (string / null, required).
* **`finished_at`** (string / null, required).
* **`coverage`** (string, required): Dataset scope and completeness, including limits on what these results establish. values: "pending", "complete\_for\_query", "capped", "partial", "unknown"
* **`coverage_reason`** (string / null, required).
* **`provider_total_count`** (integer / null, required).
* **`usage`** (object, required): additional fields rejected
* **`operation`** (string, required): must equal "backlinks"
* **`coverage_scope`** (string, required): values: "customer\_import", "corpus\_subset", "provider\_query"
* **`whole_web_coverage`** (boolean, required): False: these results do not measure the whole web. must equal false
* **`replayed`** (boolean, optional): True when the response reuses an earlier request with the same idempotency value.
* **`admission`** (object / null, optional).
* **`rejected`** (array, required).
* **`duplicates`** (array, required).
* **`rejected_total`** (number, required).
* **`duplicates_total`** (number, required).
| Field | Type | Presence | Meaning and constraints |
| --------------------------------------- | -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `v` | number | Required | must equal 1 |
| `id` | string | Required | Resource identifier returned by the operation. minLength: 1; maxLength: 128; pattern: "^\[a-zA-Z0-9\_-]+\$" |
| `workspace_id` | string | Required | Workspace that owns this record. minLength: 1; maxLength: 128; pattern: "^\[a-zA-Z0-9\_-]+\$" |
| `project_id` | string | Required | Project that owns this record. minLength: 1; maxLength: 128; pattern: "^\[a-zA-Z0-9\_-]+\$" |
| `provider` | string | Required | values: "linktrail\_corpus", "dataforseo", "imported" |
| `data_mode` | string | Required | values: "synthetic", "owned\_corpus", "provider\_index", "imported" |
| `query` | object | Required | additional fields rejected |
| `query.target_kind` | string | Required | values: "domain", "exact\_url" |
| `query.target` | string | Required | minLength: 1; maxLength: 4096 |
| `query.include_subdomains` | boolean | Required | |
| `query.backlinks_status_type` | string | Required | values: "live", "lost", "all" |
| `query.exclude_internal_backlinks` | boolean | Required | |
| `query.mode` | string | Required | must equal "as\_is" |
| `query.filters` | null | Required | |
| `query.order_by` | array | Required | minItems: 1; maxItems: 1 |
| `query.rank_scale` | string / null | Required | |
| `query.page_limit` | integer | Required | minimum: 1; maximum: 1000 |
| `query.row_limit` | integer | Required | minimum: 1; maximum: 1000 |
| `status` | string | Required | Resource lifecycle status. values: "queued", "running", "succeeded", "partial", "failed", "reconciliation\_required" |
| `created_at` | string | Required | UTC timestamp when the record was created. format: "date-time"; pattern: "^(?:(?:\d\d\[2468]\[048]\|\d\d\[13579]\[26]\|\d\d0\[48]\|\[02468]\[048]00\|\[13579]\[26]00)-02-29\|\d\{4}-(?:(?:0\[13578]\|1\[02])-(?:0\[1-9]\|\[12]\d\|3\[01])\|(?:0\[469]\|11)-(?:0\[1-9]\|\[12]\d\|30)\|(?:02)-(?:0\[1-9]\|1\d\|2\[0-8])))T(?:(?:\[01]\d\|2\[0-3]):\[0-5]\d:\[0-5]\d\\.\d\{3}(?:Z))\$" |
| `started_at` | string / null | Required | |
| `finished_at` | string / null | Required | |
| `coverage` | string | Required | Dataset scope and completeness, including limits on what these results establish. values: "pending", "complete\_for\_query", "capped", "partial", "unknown" |
| `coverage_reason` | string / null | Required | |
| `provider_total_count` | integer / null | Required | |
| `usage` | object | Required | additional fields rejected |
| `usage.unit` | string | Required | must equal "discovery" |
| `usage.currency` | string | Required | must equal "USD" |
| `usage.quote_id` | string | Required | Identifier returned by the related operation. minLength: 1; maxLength: 128; pattern: "^\[a-zA-Z0-9\_-]+\$" |
| `usage.max_cost_microusd` | integer | Required | minimum: 0; maximum: 9007199254740991 |
| `usage.reserved_cost_microusd` | integer | Required | minimum: 0; maximum: 9007199254740991 |
| `usage.provider_reported_cost_microusd` | integer / null | Required | |
| `usage.request_count` | integer | Required | minimum: 0; maximum: 9007199254740991 |
| `usage.returned_rows` | integer | Required | minimum: 0; maximum: 9007199254740991 |
| `usage.accepted_candidates` | integer | Required | minimum: 0; maximum: 9007199254740991 |
| `usage.rejected_rows` | integer | Required | minimum: 0; maximum: 9007199254740991 |
| `usage.duplicate_rows` | integer | Required | minimum: 0; maximum: 9007199254740991 |
| `operation` | string | Required | must equal "backlinks" |
| `coverage_scope` | string | Required | values: "customer\_import", "corpus\_subset", "provider\_query" |
| `whole_web_coverage` | boolean | Required | False: these results do not measure the whole web. must equal false |
| `replayed` | boolean | Optional | True when the response reuses an earlier request with the same idempotency value. |
| `admission` | object / null | Optional | |
| `admission.operation_id` | string | Required | Identifier returned by the related operation. minLength: 1; maxLength: 200 |
| `admission.project_id` | string | Required | Project that owns this record. minLength: 1; maxLength: 200 |
| `admission.context` | string | Required | values: "import", "candidate", "candidate\_batch", "serve" |
| `admission.decisions` | array | Required | |
| `admission.decisions[].index` | integer | Required | minimum: 0; maximum: 9007199254740991 |
| `admission.decisions[].url` | string | Required | |
| `admission.decisions[].normalized_url` | string / null | Required | |
| `admission.decisions[].host` | string / null | Required | |
| `admission.decisions[].decision` | string | Required | values: "admitted", "rejected" |
| `admission.decisions[].reason` | string | Required | Recorded explanation; null when no explanation applies. |
| `admission.decisions[].rule_kind` | string / null | Required | |
| `admission.decisions[].rule_id` | string / null | Required | Identifier returned by the related operation. |
| `admission.decisions[].rule_value` | string / null | Required | |
| `admission.decisions[].cap` | object / null | Required | |
| `admission.decisions[].cap.limit` | integer | Required | maximum: 9007199254740991; exclusiveMinimum: 0 |
| `admission.decisions[].cap.used` | integer | Required | minimum: 0; maximum: 9007199254740991 |
| `admission.decisions[].subject_key` | string | Required | minLength: 1; maxLength: 200 |
| `admission.summary` | object | Required | Grouped change counts included in this delivery, limited to accessible websites. additional fields rejected |
| `admission.summary.total` | integer | Required | minimum: -9007199254740991; maximum: 9007199254740991 |
| `admission.summary.admitted` | integer | Required | minimum: -9007199254740991; maximum: 9007199254740991 |
| `admission.summary.rejected` | integer | Required | minimum: -9007199254740991; maximum: 9007199254740991 |
| `admission.summary.by_rule` | object | Required | |
| `admission.policy_revision` | integer | Required | minimum: 0; maximum: 9007199254740991 |
| `admission.disavow_revision` | integer | Required | minimum: 0; maximum: 9007199254740991 |
| `admission.replayed` | boolean | Required | True when the response reuses an earlier request with the same idempotency value. |
| `rejected` | array | Required | |
| `rejected[].row` | number | Required | |
| `rejected[].reason` | string | Required | Recorded explanation; null when no explanation applies. |
| `rejected[].admission` | object | Optional | additional fields rejected |
| `rejected[].admission.index` | integer | Required | minimum: 0; maximum: 9007199254740991 |
| `rejected[].admission.url` | string | Required | |
| `rejected[].admission.normalized_url` | string / null | Required | |
| `rejected[].admission.host` | string / null | Required | |
| `rejected[].admission.decision` | string | Required | values: "admitted", "rejected" |
| `rejected[].admission.reason` | string | Required | Recorded explanation; null when no explanation applies. |
| `rejected[].admission.rule_kind` | string / null | Required | |
| `rejected[].admission.rule_id` | string / null | Required | Identifier returned by the related operation. |
| `rejected[].admission.rule_value` | string / null | Required | |
| `rejected[].admission.cap` | object / null | Required | |
| `rejected[].admission.cap.limit` | integer | Required | maximum: 9007199254740991; exclusiveMinimum: 0 |
| `rejected[].admission.cap.used` | integer | Required | minimum: 0; maximum: 9007199254740991 |
| `rejected[].admission.subject_key` | string | Required | |
| `duplicates` | array | Required | |
| `duplicates[].row` | number | Required | |
| `duplicates[].first_seen_on_row` | number | Required | |
| `rejected_total` | number | Required | |
| `duplicates_total` | number | Required | |
[Download input schema](/schemas/import_backlinks.input.json) · [Download output schema](/schemas/import_backlinks.output.json)
## Errors and retries
The command is annotated idempotent. Reuse an accepted idempotency key when the input provides one; changing the payload under a reused key can conflict.
See [error recovery](/reference/errors) for status, scope, cooldown, cursor and retry handling. Unknown observations are result data and do not establish loss.
## HTTP resource routes
These existing resource routes share the operation’s domain behavior. Their parameter placement, status and response envelope can differ from generic invocation. See [HTTP route details](/reference/http/routes).
| Method and route | Success | Details |
| ---------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
| `POST /v1/discovery/imports` | 201 | Remaining arguments go in a JSON object body. Supply idempotencyKey as the Idempotency-Key header on this resource route. |
## Continue
[get\_discovery\_run](/reference/commands/get_discovery_run) · [list\_discovery\_candidates](/reference/commands/list_discovery_candidates)
Follow the [related workflow](/guides/import-and-verify), inspect [capability status](/capability-status), or return to the [command index](/reference/index).