> ## 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.
# Preview competitor exclusions
> Dry-run exact source exclusion rules against selected frozen inventories.
`preview_competitor_exclusions`
Dry-run exact source exclusion rules against selected frozen inventories. Returns before/after counts and bounded matched/collateral examples. Does not save rules, buy discovery, check links or alter evidence.
Hosted MCP registration verified. These schemas describe the development contract; confirm supported inputs with tools/list. Generic CLI/HTTP calls require a matching development server. Configure LINKTRAIL\_API\_URL; production does not expose these command routes.
| Access | Behavior |
| ---------------- | ---------------- |
| `discovery:read` | Reads saved data |
Reading saved data does not start a verification job. Mutations can change saved records or access; the effects below apply.
## 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": "preview_competitor_exclusions",
"arguments": {
"setId": "set_example",
"revision": 1,
"inventoryIds": [
"inventory_example",
"inventory_example_1"
],
"grouping": "page"
}
}
}
```
```bash CLI theme={null}
linktrail call preview_competitor_exclusions --args '{"setId":"set_example","revision":1,"inventoryIds":["inventory_example","inventory_example_1"],"grouping":"page"}'
```
```bash HTTP theme={null}
curl "$LINKTRAIL_API_URL/v1/commands/preview_competitor_exclusions" \
-H "Authorization: Bearer $LINKTRAIL_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"setId":"set_example","revision":1,"inventoryIds":["inventory_example","inventory_example_1"],"grouping":"page"}'
```
## 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,
"set_id": "set_example",
"set_revision": 1,
"grouping": "page",
"comparison": {
"mode": "observed_overlap_only",
"reasons": [
"incomplete_query_coverage"
],
"absence_claim": "not_supported"
},
"absence_claim": "not_supported",
"whole_web_coverage": false,
"coverage_scope": "selected_inventory_datasets",
"verification_view": "captured_at_snapshot",
"max_retrieval_skew_ms": 86400000,
"selected_inventory_ids": [
"inventory_example",
"inventory_example_1"
],
"unselected_member_ids": [],
"exclusions": {
"scope": "request_only",
"policy": "any_source_row_hides_group",
"rules": []
},
"inventories": [
{
"v": 1,
"id": "inventory_example",
"workspace_id": "ws_example",
"project_id": "pr_example",
"set_id": "set_example",
"set_revision": 1,
"set_hash": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
"member_id": "cm_customer",
"member_role": "customer",
"target_scope_id": "ts_example",
"captured_at": "2026-09-13T12:00:00.000Z",
"provider_retrieved_from": "2026-09-13T12:00:00.000Z",
"provider_retrieved_to": "2026-09-13T12:00:00.000Z",
"run": {
"v": 1,
"id": "dr_example",
"workspace_id": "ws_example",
"project_id": "pr_example",
"provider": "linktrail_corpus",
"data_mode": "owned_corpus",
"query": {
"target_kind": "domain",
"target": "example.com",
"include_subdomains": true,
"backlinks_status_type": "live",
"exclude_internal_backlinks": true,
"mode": "as_is",
"filters": null,
"order_by": [
"first_seen,desc"
],
"rank_scale": null,
"page_limit": 100,
"row_limit": 100
},
"status": "succeeded",
"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": "complete_for_query",
"coverage_reason": null,
"provider_total_count": 1,
"usage": {
"unit": "discovery",
"currency": "USD",
"quote_id": "owned_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": "corpus_subset",
"whole_web_coverage": false
},
"content_hash": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
"absence_claim": "not_supported",
"verification_view": "captured_at_snapshot"
},
{
"v": 1,
"id": "inventory_example_1",
"workspace_id": "ws_example",
"project_id": "pr_example",
"set_id": "set_example",
"set_revision": 1,
"set_hash": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
"member_id": "cm_competitor",
"member_role": "competitor",
"target_scope_id": "ts_example",
"captured_at": "2026-09-13T12:00:00.000Z",
"provider_retrieved_from": "2026-09-13T12:00:00.000Z",
"provider_retrieved_to": "2026-09-13T12:00:00.000Z",
"run": {
"v": 1,
"id": "dr_example",
"workspace_id": "ws_example",
"project_id": "pr_example",
"provider": "linktrail_corpus",
"data_mode": "owned_corpus",
"query": {
"target_kind": "domain",
"target": "competitor.example.org",
"include_subdomains": true,
"backlinks_status_type": "live",
"exclude_internal_backlinks": true,
"mode": "as_is",
"filters": null,
"order_by": [
"first_seen,desc"
],
"rank_scale": null,
"page_limit": 100,
"row_limit": 100
},
"status": "succeeded",
"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": "row_limit",
"provider_total_count": 1,
"usage": {
"unit": "discovery",
"currency": "USD",
"quote_id": "owned_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": "corpus_subset",
"whole_web_coverage": false
},
"content_hash": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
"absence_claim": "not_supported",
"verification_view": "captured_at_snapshot"
}
],
"baseline_report_hash": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
"preview_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"dry_run": true,
"before_counts": {
"groups": 1,
"rows": 2,
"observed_overlap_groups": 1,
"dataset_gap_groups": null,
"comparison_unknown_groups": 0,
"excluded_groups": 0,
"excluded_rows": 0
},
"after_counts": {
"groups": 1,
"rows": 2,
"observed_overlap_groups": 1,
"dataset_gap_groups": null,
"comparison_unknown_groups": 0,
"excluded_groups": 0,
"excluded_rows": 0
},
"per_rule": [],
"per_rule_counts_overlap": true,
"examples": [],
"examples_truncated": false,
"example_limits": {
"groups": 10,
"matches_per_group": 3
}
}
```
## Input fields
Omit optional fields when you do not want to supply them. Null is accepted only where listed. Unknown input properties are rejected.
| Field | Type | Presence | Meaning and constraints |
| ----------------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `setId` | string | Required | Identifier of the set returned by its create or list operation. minLength: 1; maxLength: 200 |
| `revision` | integer | Required | Immutable set revision to read or compare. minimum: 1; maximum: 9007199254740990 |
| `inventoryIds` | array | Required | Frozen inventory IDs to compare; records must belong to the approved set. minItems: 2; maxItems: 11 |
| `grouping` | string | Required | Grouping dimension used to aggregate the selected inventories. values: "page", "source\_host" |
| `exclusions` | array | Optional | Customer-approved exclusions to apply to this report. maxItems: 100; default: \[] |
| `exclusions[].grouping` | string | Required | See the typed schema and response example for this field. values: "page", "source\_host" |
| `exclusions[].value` | string | Required | See the typed schema and response example for this field. minLength: 1; maxLength: 4096 |
| `maxRetrievalSkewMs` | integer | Optional | Maximum permitted difference between inventory retrieval times, in milliseconds. minimum: 0; maximum: 86400000; default: 86400000 |
| `exclusionRevision` | integer | Optional | Saved exclusion revision to apply; historical revisions remain immutable. minimum: 1; maximum: 9007199254740990 |
### Validation and omitted values
grouping is required: there is no implicit page/host grouping. Select exclusionRevision explicitly to apply saved rules; omitted exclusionRevision uses only request exclusions.
Selected inventories must be distinct, compatible with the approved revision and include the required customer inventory. Missing dataset edges cannot establish web-wide absence.
### Defaults when omitted
| Field | Default |
| -------------------- | ---------- |
| `exclusions` | `[]` |
| `maxRetrievalSkewMs` | `86400000` |
## 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.
| Field | Type | Presence | Meaning and constraints |
| --------------------------------------------------------- | -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `v` | number | Required | v recorded for this result. |
| `set_id` | string | Required | set id recorded for this result. |
| `set_revision` | number | Required | set revision recorded for this result. |
| `grouping` | string | Required | grouping recorded for this result. |
| `comparison` | object | Required | comparison recorded for this result. |
| `comparison.mode` | string | Required | mode recorded for this result. |
| `comparison.reasons` | array | Required | reasons recorded for this result. |
| `comparison.absence_claim` | string | Required | not\_supported: missing dataset rows cannot prove link absence. must equal "not\_supported" |
| `absence_claim` | string | Required | not\_supported: missing dataset rows cannot prove link absence. must equal "not\_supported" |
| `whole_web_coverage` | boolean | Required | False: these results do not measure the whole web. must equal false |
| `coverage_scope` | string | Required | coverage scope recorded for this result. |
| `verification_view` | string | Required | verification view recorded for this result. |
| `max_retrieval_skew_ms` | number | Required | max retrieval skew ms recorded for this result. |
| `selected_inventory_ids` | array | Required | selected inventory ids recorded for this result. |
| `unselected_member_ids` | array | Required | unselected member ids recorded for this result. |
| `exclusions` | object | Required | exclusions recorded for this result. |
| `exclusions.scope` | string | Required | scope recorded for this result. |
| `exclusions.policy` | string | Required | policy recorded for this result. |
| `exclusions.rules` | array | Required | rules recorded for this result. |
| `exclusions.rules[].grouping` | string | Required | grouping recorded for this result. values: "page", "source\_host" |
| `exclusions.rules[].value` | string | Required | value recorded for this result. |
| `exclusions.saved_revision` | number | Optional | saved revision recorded for this result. |
| `exclusions.set_revision_at_save` | number | Optional | set revision at save recorded for this result. |
| `inventories` | array | Required | inventories recorded for this result. |
| `inventories[].v` | number | Required | v recorded for this result. |
| `inventories[].id` | string | Required | Resource identifier returned by the operation. |
| `inventories[].workspace_id` | string | Required | Workspace that owns this record. |
| `inventories[].project_id` | string | Required | Project that owns this record. |
| `inventories[].set_id` | string | Required | set id recorded for this result. |
| `inventories[].set_revision` | number | Required | set revision recorded for this result. |
| `inventories[].set_hash` | string | Required | set hash recorded for this result. |
| `inventories[].member_id` | string | Required | member id recorded for this result. |
| `inventories[].member_role` | string | Required | member role recorded for this result. |
| `inventories[].target_scope_id` | string | Required | target scope id recorded for this result. |
| `inventories[].captured_at` | string | Required | captured at recorded for this result. |
| `inventories[].provider_retrieved_from` | string / null | Required | provider retrieved from recorded for this result. |
| `inventories[].provider_retrieved_to` | string / null | Required | provider retrieved to recorded for this result. |
| `inventories[].run` | object | Required | run recorded for this result. |
| `inventories[].run.v` | number | Required | v recorded for this result. must equal 1 |
| `inventories[].run.id` | string | Required | Resource identifier returned by the operation. minLength: 1; maxLength: 128; pattern: "^\[a-zA-Z0-9\_-]+\$" |
| `inventories[].run.workspace_id` | string | Required | Workspace that owns this record. minLength: 1; maxLength: 128; pattern: "^\[a-zA-Z0-9\_-]+\$" |
| `inventories[].run.project_id` | string | Required | Project that owns this record. minLength: 1; maxLength: 128; pattern: "^\[a-zA-Z0-9\_-]+\$" |
| `inventories[].run.provider` | string | Required | provider recorded for this result. values: "linktrail\_corpus", "dataforseo", "imported" |
| `inventories[].run.data_mode` | string | Required | data mode recorded for this result. values: "synthetic", "owned\_corpus", "provider\_index", "imported" |
| `inventories[].run.query` | object | Required | query recorded for this result. additional fields rejected |
| `inventories[].run.query.target_kind` | string | Required | target kind recorded for this result. values: "domain", "exact\_url" |
| `inventories[].run.query.target` | string | Required | target recorded for this result. minLength: 1; maxLength: 4096 |
| `inventories[].run.query.include_subdomains` | boolean | Required | include subdomains recorded for this result. |
| `inventories[].run.query.backlinks_status_type` | string | Required | backlinks status type recorded for this result. values: "live", "lost", "all" |
| `inventories[].run.query.exclude_internal_backlinks` | boolean | Required | exclude internal backlinks recorded for this result. |
| `inventories[].run.query.mode` | string | Required | mode recorded for this result. must equal "as\_is" |
| `inventories[].run.query.filters` | null | Required | filters recorded for this result. |
| `inventories[].run.query.order_by` | array | Required | order by recorded for this result. minItems: 1; maxItems: 1 |
| `inventories[].run.query.rank_scale` | string / null | Required | rank scale recorded for this result. |
| `inventories[].run.query.page_limit` | integer | Required | page limit recorded for this result. minimum: 1; maximum: 1000 |
| `inventories[].run.query.row_limit` | integer | Required | row limit recorded for this result. minimum: 1; maximum: 1000 |
| `inventories[].run.status` | string | Required | Resource lifecycle status. values: "queued", "running", "succeeded", "partial", "failed", "reconciliation\_required" |
| `inventories[].run.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))\$" |
| `inventories[].run.started_at` | string / null | Required | started at recorded for this result. |
| `inventories[].run.finished_at` | string / null | Required | finished at recorded for this result. |
| `inventories[].run.coverage` | string | Required | Dataset scope and completeness, including limits on what these results establish. values: "pending", "complete\_for\_query", "capped", "partial", "unknown" |
| `inventories[].run.coverage_reason` | string / null | Required | coverage reason recorded for this result. |
| `inventories[].run.provider_total_count` | integer / null | Required | provider total count recorded for this result. |
| `inventories[].run.usage` | object | Required | usage recorded for this result. additional fields rejected |
| `inventories[].run.usage.unit` | string | Required | unit recorded for this result. must equal "discovery" |
| `inventories[].run.usage.currency` | string | Required | currency recorded for this result. must equal "USD" |
| `inventories[].run.usage.quote_id` | string | Required | quote id recorded for this result. minLength: 1; maxLength: 128; pattern: "^\[a-zA-Z0-9\_-]+\$" |
| `inventories[].run.usage.max_cost_microusd` | integer | Required | max cost microusd recorded for this result. minimum: 0; maximum: 9007199254740991 |
| `inventories[].run.usage.reserved_cost_microusd` | integer | Required | reserved cost microusd recorded for this result. minimum: 0; maximum: 9007199254740991 |
| `inventories[].run.usage.provider_reported_cost_microusd` | integer / null | Required | provider reported cost microusd recorded for this result. |
| `inventories[].run.usage.request_count` | integer | Required | request count recorded for this result. minimum: 0; maximum: 9007199254740991 |
| `inventories[].run.usage.returned_rows` | integer | Required | returned rows recorded for this result. minimum: 0; maximum: 9007199254740991 |
| `inventories[].run.usage.accepted_candidates` | integer | Required | accepted candidates recorded for this result. minimum: 0; maximum: 9007199254740991 |
| `inventories[].run.usage.rejected_rows` | integer | Required | rejected rows recorded for this result. minimum: 0; maximum: 9007199254740991 |
| `inventories[].run.usage.duplicate_rows` | integer | Required | duplicate rows recorded for this result. minimum: 0; maximum: 9007199254740991 |
| `inventories[].run.operation` | string | Required | operation recorded for this result. must equal "backlinks" |
| `inventories[].run.coverage_scope` | string | Required | coverage scope recorded for this result. values: "customer\_import", "corpus\_subset", "provider\_query" |
| `inventories[].run.whole_web_coverage` | boolean | Required | False: these results do not measure the whole web. must equal false |
| `inventories[].run.replayed` | boolean | Optional | True when the response reuses an earlier request with the same idempotency value. |
| `inventories[].content_hash` | string | Required | content hash recorded for this result. |
| `inventories[].absence_claim` | string | Required | not\_supported: missing dataset rows cannot prove link absence. must equal "not\_supported" |
| `inventories[].verification_view` | string | Required | verification view recorded for this result. must equal "captured\_at\_snapshot" |
| `inventories[].replayed` | boolean | Optional | True when the response reuses an earlier request with the same idempotency value. |
| `baseline_report_hash` | string | Required | baseline report hash recorded for this result. |
| `preview_hash` | string | Required | preview hash recorded for this result. |
| `dry_run` | boolean | Required | dry run recorded for this result. must equal true |
| `before_counts` | object / null | Required | before counts recorded for this result. |
| `before_counts.groups` | number | Required | groups recorded for this result. |
| `before_counts.rows` | number | Required | rows recorded for this result. |
| `before_counts.observed_overlap_groups` | number | Required | observed overlap groups recorded for this result. |
| `before_counts.dataset_gap_groups` | number / null | Required | dataset gap groups recorded for this result. |
| `before_counts.comparison_unknown_groups` | number | Required | comparison unknown groups recorded for this result. |
| `before_counts.excluded_groups` | number | Required | excluded groups recorded for this result. |
| `before_counts.excluded_rows` | number | Required | excluded rows recorded for this result. |
| `after_counts` | object / null | Required | after counts recorded for this result. |
| `after_counts.groups` | number | Required | groups recorded for this result. |
| `after_counts.rows` | number | Required | rows recorded for this result. |
| `after_counts.observed_overlap_groups` | number | Required | observed overlap groups recorded for this result. |
| `after_counts.dataset_gap_groups` | number / null | Required | dataset gap groups recorded for this result. |
| `after_counts.comparison_unknown_groups` | number | Required | comparison unknown groups recorded for this result. |
| `after_counts.excluded_groups` | number | Required | excluded groups recorded for this result. |
| `after_counts.excluded_rows` | number | Required | excluded rows recorded for this result. |
| `per_rule` | array | Required | per rule recorded for this result. |
| `per_rule[].rule` | object | Required | rule recorded for this result. |
| `per_rule[].rule.grouping` | string | Required | grouping recorded for this result. values: "page", "source\_host" |
| `per_rule[].rule.value` | string | Required | value recorded for this result. |
| `per_rule[].matched_rows` | number / null | Required | matched rows recorded for this result. |
| `per_rule[].hidden_groups` | number / null | Required | hidden groups recorded for this result. |
| `per_rule[].hidden_rows` | number / null | Required | hidden rows recorded for this result. |
| `per_rule_counts_overlap` | boolean | Required | per rule counts overlap recorded for this result. |
| `examples` | array | Required | examples recorded for this result. |
| `examples[].group_key` | string | Required | Exact group identifier used to retrieve contributor rows. |
| `examples[].relation` | string | Required | relation recorded for this result. |
| `examples[].hidden_rows` | number | Required | hidden rows recorded for this result. |
| `examples[].matched_rows` | number | Required | matched rows recorded for this result. |
| `examples[].collateral_rows` | number | Required | collateral rows recorded for this result. |
| `examples[].matches` | array | Required | matches recorded for this result. |
| `examples[].matches[].candidate_id` | string | Required | candidate id recorded for this result. |
| `examples[].matches[].source_url` | string | Required | Publisher page URL recorded in this evidence. |
| `examples[].matches[].target_url` | string | Required | Destination URL recorded in this evidence. |
| `examples[].matches[].inventory_id` | string | Required | inventory id recorded for this result. |
| `examples[].matches[].member_id` | string | Required | member id recorded for this result. |
| `examples[].matches[].member_role` | string | Required | member role recorded for this result. |
| `examples[].matches[].rule_indexes` | array | Required | rule indexes recorded for this result. |
| `examples[].matches_truncated` | boolean | Required | matches truncated recorded for this result. |
| `examples_truncated` | boolean | Required | examples truncated recorded for this result. |
| `example_limits` | object | Required | example limits recorded for this result. |
| `example_limits.groups` | number | Required | groups recorded for this result. |
| `example_limits.matches_per_group` | number | Required | matches per group recorded for this result. |
[Download input schema](/schemas/preview_competitor_exclusions.input.json) · [Download output schema](/schemas/preview_competitor_exclusions.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/competitor-sets/{setId}/exclusions/preview` | 200 | Remaining arguments go in a JSON object body. |
## Continue
[get\_competitor\_exclusions](/reference/commands/get_competitor_exclusions)
Follow the [related workflow](/guides/competitor-research), inspect [capability status](/capability-status), or return to the [command index](/reference/index).