---
title: "Start competitor supplier research"
method: POST
path: "/v1/commands/start_competitor_supplier_inventory"
tags: ["Competitor research"]
---

# Start competitor supplier research

`POST /v1/commands/start_competitor_supplier_inventory`

## Request

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

Shared command transport. All logical arguments in JSON; no query or Idempotency-Key header. See canonical operation reference.

## Headers

- `X-Workspace-ID` string

## Request body

- StartCompetitorSupplierInventoryInput
  - `offerId` string, required: offer ID from create/list.
  - `idempotencyKey` string, required: Caller-generated key reused only for retries of the same operation and arguments in this workspace.
  - `consent` true, required

## Response `200`

Command result, including queued admission.

- StartCompetitorSupplierInventoryOutput
  - `schema_version` union, required
    - 1
    - 2
  - `id` string, required: Resource identifier returned by the operation.
  - `workspace_id` string, required: Workspace that owns this record.
  - `competitor_binding` object
    - `setId` string, required
    - `revision` integer, required: Revision of the approved competitor set bound to this offer or run. Pass the current set revision as revision when preparing an offer.
    - `memberId` string, required
  - `project_id` string, required: Project that owns this record.
  - `scope` object, required
    - `domain` string, required
    - `include_subdomains` boolean, required
    - `website_revision` string, required
    - `query_version` 'dataforseo-as-is-v1', required
  - `source` 'dataforseo', required
  - `data_mode` 'synthetic' | 'provider_index', required
  - `state` 'queued' | 'fetching' | 'checking' | 'ready' | 'partial' | 'empty' | 'failed' | 'cancelled' | 'reconciliation_required', required: Saved lifecycle or evidence state, as enumerated for this record.
  - `created_at` string, date-time, required: UTC timestamp when the record was created.
  - `updated_at` string, date-time, required: UTC timestamp of the last record update.
  - `execution_deadline` string, date-time, required
  - `timing` object, required
    - `first_result_at` string, date-time, nullable, required
    - `finished_at` string, date-time, nullable, required
    - `first_result_ms` integer, nullable, required
  - `components` object, required
    - `summary` object, required: Grouped change counts included in this delivery, limited to accessible websites.
      - `state` 'pending' | 'running' | 'succeeded' | 'partial' | 'empty' | 'failed' | 'cancelled' | 'reconciliation_required', required: Saved lifecycle or evidence state, as enumerated for this record.
      - `run_id` string, nullable, required
      - `retrieved_at` string, date-time, nullable, required
      - `error_code` string, nullable, required: Latest delivery detail code; null when no failure or retry has been recorded.
    - `list` object, required
      - `state` 'pending' | 'running' | 'succeeded' | 'partial' | 'empty' | 'failed' | 'cancelled' | 'reconciliation_required', required: Saved lifecycle or evidence state, as enumerated for this record.
      - `run_id` string, nullable, required
      - `retrieved_at` string, date-time, nullable, required
      - `error_code` string, nullable, required: Latest delivery detail code; null when no failure or retry has been recorded.
    - `checks` object, required
      - `state` 'pending' | 'running' | 'succeeded' | 'partial' | 'empty' | 'failed' | 'cancelled' | 'reconciliation_required' | 'not_requested', required: Saved lifecycle or evidence state, as enumerated for this record.
      - `run_id` string, nullable, required
      - `retrieved_at` string, date-time, nullable, required
      - `error_code` string, nullable, required: Latest delivery detail code; null when no failure or retry has been recorded.
  - `summary` object, nullable, required: Grouped change counts included in this delivery, limited to accessible websites.
    - `v` 1, required
    - `overview_run_id` string, required
    - `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
    - `provider_retrieved_at` string, date-time, required: Timestamp when the upstream evidence was retrieved.
    - `provider_first_seen` string, date-time, nullable, required
    - `provider_lost_date` string, date-time, nullable, required
    - `verified_at` unknown, required
    - `coverage` 'provider_summary' | 'corpus_subset' | 'partial', required: Dataset scope and completeness, including limits on what these results establish.
    - `counts` object, required
      - `backlinks` integer, nullable, required
      - `referring_domains` integer, nullable, required
      - `referring_main_domains` integer, nullable, required
      - `referring_pages` integer, nullable, required
      - `referring_ips` integer, nullable, required
      - `referring_subnets` integer, nullable, required
      - `crawled_pages` integer, nullable, required
      - `broken_backlinks` integer, nullable, required
      - `broken_pages` integer, nullable, required
    - `provider_metrics` union, required
      - object
        - `dataforseo` object, required
          - `rank` integer, nullable, required
          - `backlinks_spam_score` integer, nullable, required
          - `rank_scale` 'one_thousand', required
      - object
        - `linktrail_corpus` object, required
          - `corpus_source_pages` integer, nullable, required
          - `corpus_last_expanded_at` string, date-time, nullable, required
  - `counts` object, required
    - `indexed_total` integer, nullable, required
    - `retrieved_candidates` integer, required
    - `selected_checks` integer, required
    - `checked` integer, required
    - `present` integer, required
    - `absent` integer, required
    - `source_unavailable` integer, required
    - `unknown` integer, required
  - `coverage` object, required: Dataset scope and completeness, including limits on what these results establish.
    - `whole_web` false, required
    - `sample` true, required: True: the rendered preview uses example content, never customer events.
    - `ordering` 'rank,desc', required
    - `reason` string, nullable, required: Recorded explanation; null when no explanation applies.
  - `selection` object, required
    - `policy` 'distinct-host-target-order-v1', required
    - `manifest_hash` string, nullable, required
    - `candidate_ids` string[], required
    - `render_limit` 0, required
  - `recurring_monitoring_created` false, required: Whether this operation enrolled recurring monitoring.
  - `recovery` 'read_saved_run' | 'reconcile_receipt' | 'explicit_new_offer', required
  - `replayed` boolean: True when the response reuses an earlier request with the same idempotency value.

## 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)