> ## 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.
# Request domain overview
> Request a separately metered supplier summary for a domain or subdomain.
`request_domain_overview`
Request a separately metered supplier summary for a domain or subdomain. Admission is disabled in this build and cannot be configured by retrying. An operator must provide a supported supplier admission path before this command can run. Summaries carry their data mode and provider provenance; they are not link checks or totals derived from selected candidates.
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:write` | Writes or admits work |
Provider-backed admission requires enabled configuration and available allowance; registration alone does not make retrieval available. Inspect usage and the run’s coverage before interpreting results.
## 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": "request_domain_overview",
"arguments": {
"projectId": "project_example",
"target": "example.com",
"includeSubdomains": false,
"includeIndirectLinks": false,
"excludeInternalBacklinks": false,
"backlinksStatus": "live",
"idempotencyKey": "docs-request-001"
}
}
}
```
```bash CLI theme={null}
linktrail call request_domain_overview --args '{"projectId":"project_example","target":"example.com","includeSubdomains":false,"includeIndirectLinks":false,"excludeInternalBacklinks":false,"backlinksStatus":"live","idempotencyKey":"docs-request-001"}'
```
```bash HTTP theme={null}
curl "$LINKTRAIL_API_URL/v1/commands/request_domain_overview" \
-H "Authorization: Bearer $LINKTRAIL_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"projectId":"project_example","target":"example.com","includeSubdomains":false,"includeIndirectLinks":false,"excludeInternalBacklinks":false,"backlinksStatus":"live","idempotencyKey":"docs-request-001"}'
```
## 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": "overview_example",
"workspace_id": "ws_example",
"project_id": "project_example",
"operation": "domain_overview",
"provider": "dataforseo",
"data_mode": "synthetic",
"query": {
"target": "example.com",
"include_subdomains": false,
"include_indirect_links": false,
"exclude_internal_backlinks": false,
"backlinks_status_type": "live",
"backlinks_filters": null,
"rank_scale": "one_thousand",
"internal_list_limit": 10
},
"status": "queued",
"created_at": "2026-09-13T12:00:00.000Z",
"started_at": null,
"finished_at": null,
"error_code": null,
"result": null,
"usage": {
"unit": "domain_overview",
"currency": "USD",
"quote_id": "synthetic_example",
"max_cost_microusd": 1,
"reserved_cost_microusd": 0,
"provider_reported_cost_microusd": null,
"request_count": 0,
"summaries_returned": 0
},
"coverage": "pending",
"coverage_scope": "provider_query",
"whole_web_coverage": false,
"replayed": false
}
```
## 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 |
| -------------------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `projectId` | string | Required | Identifier of the project returned by its create or list operation. pattern: "^\[a-zA-Z0-9\_-]\{1,128}\$" |
| `target` | string | Required | Exact URL or domain to query, interpreted according to targetKind. minLength: 1; maxLength: 253 |
| `includeSubdomains` | boolean | Required | Include subdomains of the selected domain in this query. |
| `includeIndirectLinks` | boolean | Required | Include indirect supplier-reported links where supported. |
| `excludeInternalBacklinks` | boolean | Required | Exclude supplier rows linking within the queried site. |
| `backlinksStatus` | string | Required | Supplier-reported backlink status filter; this is not Linktrail verification. values: "live", "lost", "all" |
| `idempotencyKey` | string | Required | 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, includeIndirectLinks, excludeInternalBacklinks and backlinksStatus are required. The provider source and internal list limit are server-owned.
Current ordinary admission is unavailable. A supported operator configuration is required; retrying cannot activate a supplier.
## 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. must equal 1 |
| `id` | string | Required | Resource identifier returned by the operation. pattern: "^\[a-zA-Z0-9\_-]\{1,128}\$" |
| `workspace_id` | string | Required | Workspace that owns this record. pattern: "^\[a-zA-Z0-9\_-]\{1,128}\$" |
| `project_id` | string | Required | Project that owns this record. pattern: "^\[a-zA-Z0-9\_-]\{1,128}\$" |
| `operation` | string | Required | operation recorded for this result. must equal "domain\_overview" |
| `provider` | string | Required | provider recorded for this result. values: "linktrail\_corpus", "dataforseo", "imported" |
| `data_mode` | string | Required | data mode recorded for this result. values: "synthetic", "owned\_corpus", "provider\_index", "imported" |
| `query` | object | Required | query recorded for this result. additional fields rejected |
| `query.target` | string | Required | target recorded for this result. minLength: 1; maxLength: 253 |
| `query.include_subdomains` | boolean | Required | include subdomains recorded for this result. |
| `query.include_indirect_links` | boolean | Required | include indirect links recorded for this result. |
| `query.exclude_internal_backlinks` | boolean | Required | exclude internal backlinks recorded for this result. |
| `query.backlinks_status_type` | string | Required | backlinks status type recorded for this result. values: "live", "lost", "all" |
| `query.backlinks_filters` | null | Required | backlinks filters recorded for this result. |
| `query.rank_scale` | string / null | Required | rank scale recorded for this result. |
| `query.internal_list_limit` | number | Required | internal list limit recorded for this result. must equal 10 |
| `status` | string | Required | Resource lifecycle status. values: "queued", "running", "succeeded", "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 | started at recorded for this result. |
| `finished_at` | string / null | Required | finished at recorded for this result. |
| `error_code` | string / null | Required | error code recorded for this result. |
| `usage` | object | Required | usage recorded for this result. additional fields rejected |
| `usage.unit` | string | Required | unit recorded for this result. must equal "domain\_overview" |
| `usage.currency` | string | Required | currency recorded for this result. must equal "USD" |
| `usage.quote_id` | string | Required | quote id recorded for this result. pattern: "^\[a-zA-Z0-9\_-]\{1,128}\$" |
| `usage.max_cost_microusd` | integer | Required | max cost microusd recorded for this result. maximum: 9007199254740991; exclusiveMinimum: 0 |
| `usage.reserved_cost_microusd` | integer | Required | reserved cost microusd recorded for this result. minimum: 0; maximum: 9007199254740991 |
| `usage.provider_reported_cost_microusd` | integer / null | Required | provider reported cost microusd recorded for this result. |
| `usage.request_count` | integer | Required | request count recorded for this result. minimum: 0; maximum: 1 |
| `usage.summaries_returned` | integer | Required | summaries returned recorded for this result. minimum: 0; maximum: 1 |
| `result` | object / null | Required | Saved result; null when this operation has no completed result. |
| `result.v` | number | Required | v recorded for this result. must equal 1 |
| `result.overview_run_id` | string | Required | overview run id recorded for this result. pattern: "^\[a-zA-Z0-9\_-]\{1,128}\$" |
| `result.workspace_id` | string | Required | Workspace that owns this record. pattern: "^\[a-zA-Z0-9\_-]\{1,128}\$" |
| `result.project_id` | string | Required | Project that owns this record. pattern: "^\[a-zA-Z0-9\_-]\{1,128}\$" |
| `result.provider` | string | Required | provider recorded for this result. values: "linktrail\_corpus", "dataforseo", "imported" |
| `result.data_mode` | string | Required | data mode recorded for this result. values: "synthetic", "owned\_corpus", "provider\_index", "imported" |
| `result.provider_retrieved_at` | string | Required | Timestamp when the upstream evidence was retrieved. 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))\$" |
| `result.provider_first_seen` | string / null | Required | provider first seen recorded for this result. |
| `result.provider_lost_date` | string / null | Required | provider lost date recorded for this result. |
| `result.verified_at` | null | Required | Timestamp of the Linktrail check; null until checked. |
| `result.coverage` | string | Required | Dataset scope and completeness, including limits on what these results establish. values: "provider\_summary", "corpus\_subset", "partial" |
| `result.counts` | object | Required | counts recorded for this result. additional fields rejected |
| `result.counts.backlinks` | integer / null | Required | backlinks recorded for this result. |
| `result.counts.referring_domains` | integer / null | Required | referring domains recorded for this result. |
| `result.counts.referring_main_domains` | integer / null | Required | referring main domains recorded for this result. |
| `result.counts.referring_pages` | integer / null | Required | referring pages recorded for this result. |
| `result.counts.referring_ips` | integer / null | Required | referring ips recorded for this result. |
| `result.counts.referring_subnets` | integer / null | Required | referring subnets recorded for this result. |
| `result.counts.crawled_pages` | integer / null | Required | crawled pages recorded for this result. |
| `result.counts.broken_backlinks` | integer / null | Required | broken backlinks recorded for this result. |
| `result.counts.broken_pages` | integer / null | Required | broken pages recorded for this result. |
| `result.provider_metrics` | object / object | Required | provider metrics recorded for this result. |
| `result.provider_metrics.dataforseo` | object | Required | dataforseo recorded for this result. additional fields rejected |
| `result.provider_metrics.dataforseo.rank` | integer / null | Required | rank recorded for this result. |
| `result.provider_metrics.dataforseo.backlinks_spam_score` | integer / null | Required | backlinks spam score recorded for this result. |
| `result.provider_metrics.dataforseo.rank_scale` | string | Required | rank scale recorded for this result. must equal "one\_thousand" |
| `result.provider_metrics.linktrail_corpus` | object | Required | linktrail corpus recorded for this result. additional fields rejected |
| `result.provider_metrics.linktrail_corpus.corpus_source_pages` | integer / null | Required | corpus source pages recorded for this result. |
| `result.provider_metrics.linktrail_corpus.corpus_last_expanded_at` | string / null | Required | corpus last expanded at recorded for this result. |
| `coverage` | string | Required | Dataset scope and completeness, including limits on what these results establish. |
| `coverage_scope` | string | Required | coverage scope recorded for this result. must equal "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. |
[Download input schema](/schemas/request_domain_overview.input.json) · [Download output schema](/schemas/request_domain_overview.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/overviews` | 202 | Remaining arguments go in a JSON object body. Supply idempotencyKey as the Idempotency-Key header on this resource route. |
## Continue
[get\_domain\_overview](/reference/commands/get_domain_overview)
Follow the [related workflow](/guides/import-and-verify), inspect [capability status](/capability-status), or return to the [command index](/reference/index).