---
title: "List opportunities"
method: POST
path: "/v1/commands/list_opportunities"
tags: ["Imports and discovery"]
---

# List opportunities

`POST /v1/commands/list_opportunities`

## Request

- Base URL: `https://app.agentlinkops.com`
- URL: `https://app.agentlinkops.com/v1/commands/list_opportunities`
- 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

- ListOpportunitiesInput
  - `niche` string: Niche id from the library niche table, for example us-probate. Omit to read every niche.
  - `opportunityType` 'directory' | 'resource_page' | 'listicle_or_review' | 'guest_post_program' | 'link_insertion' | 'ai_citation_source': How a link would be earned on the surface: one of the six library opportunity types.
  - `status` 'held' | 'published' | 'withdrawn': Record status: held, published or withdrawn. Records are never deleted, so withdrawn records remain readable with their reason.
  - `routeState` 'verified' | 'partial' | 'unverified': Route verification state: verified (route page read and states the route), partial (renders client-side) or unverified (could not be read).
  - `freshness` 'fresh' | 'aging' | 'stale': Age of the last verification against the fixed 90-day window: fresh (under 60 days), aging (60 to 90 days) or stale (over 90 days or never verified). Computed at read time.
  - `sourceClass` 'owned_corpus' | 'directory_inventory' | 'cc_host_graph_seed' | 'consented_project_lane' | 'owned_submission': Provenance source class, which decides redistribution rights per class, never per row.
  - `updatedSince` string, date-time: ISO 8601 timestamp; only records whose dates.updated_at is at or after this instant are returned.
  - `cursor` string: Opaque list cursor; omit initially.
  - `limit` integer: Maximum records in this page, 1 to 100; defaults to 100.
  - `browse` boolean: Server-sorted authorized saved rows; omit for legacy paging.
  - `sort` string: Allowlisted saved-field identifier.
  - `order` 'asc' | 'desc': Sort direction; stable ID ties, nulls last.
  - `q` string: Literal search of supported saved fields.
  - `table_filters` union: Up to 12 allowlisted column filters before paging.
    - string
    - object[]
      - `column` string, required
      - `operator` 'contains' | 'is' | 'is_not' | 'empty', required
      - `value` string, required

## Response `200`

Command result, including queued admission.

- ListOpportunitiesOutput
  - `total` integer, nullable
  - `has_more` boolean, required: True when another page is available.
  - `next_cursor` string, nullable, required: Opaque continuation for the same listing; null means no further page.
  - `page` object
    - `limit` integer, required
    - `sort` string, required
    - `order` 'asc' | 'desc', required
    - `total` integer, nullable, required
    - `query_scope` 'server_dataset', required
    - `nulls` 'last', required
  - `schema_version` 1, required
  - `read_at` string, required: UTC timestamp the read used for freshness.
  - `freshness_basis` object, required: The instant and the window and aging constants that produced every freshness value in this answer.
    - `now` string, required
    - `window_days` 90, required
    - `aging_from_day` 60, required
  - `absence_claim` 'not_supported', required: not_supported: missing dataset rows cannot prove link absence.
  - `whole_web_coverage` false, required: False: these results do not measure the whole web.
  - `absence_note` string, required: Plain statement that a surface missing from this result was not read; it is never evidence that no opportunity exists.
  - `coverage` object[], required: Coverage block per niche and source read: run, dates, pages and hosts read, records emitted, and the two fixed absence literals.
    - `schema_version` 1, required
    - `niche` object, required
      - `id` string, required: Resource identifier returned by the operation.
      - `label` string, required
    - `source_class` 'owned_corpus' | 'directory_inventory' | 'cc_host_graph_seed' | 'consented_project_lane' | 'owned_submission', required
    - `run_id` string, nullable, required
    - `generated_at` string, date-time, required
    - `scope` string, required
    - `pages_read` integer, required
    - `hosts_read` integer, required
    - `records_emitted` integer, required
    - `absence_claim` 'not_supported', required: not_supported: missing dataset rows cannot prove link absence.
    - `whole_web_coverage` false, required: False: these results do not measure the whole web.
  - `filters` object, required: The filters applied to this answer, each stated even when null, so an empty page is legible.
    - `niche` string, nullable, required
    - `opportunityType` string, nullable, required
    - `status` string, nullable, required: Resource lifecycle status.
    - `routeState` string, nullable, required
    - `freshness` string, nullable, required
    - `sourceClass` string, nullable, required
    - `updatedSince` string, nullable, required
  - `ordering` string, required: Recorded page ordering. Legacy reads use update time then record ID; browse reads name their allowlisted column and direction.
  - `limit` number, required
  - `items` object[], required: Records in this bounded page.
    - `schema_version` 1, required
    - `record_id` string, required
    - `status` 'held' | 'published' | 'withdrawn', required: Resource lifecycle status.
    - `niche` object, required
      - `id` string, required: Resource identifier returned by the operation.
      - `label` string, required
    - `opportunity_type` 'directory' | 'resource_page' | 'listicle_or_review' | 'guest_post_program' | 'link_insertion' | 'ai_citation_source', required
    - `type_basis` 'observed' | 'heuristic', required
    - `subject` object, required
      - `host` string, required
      - `page_url` string, uri, nullable, required
      - `route_url` string, uri, nullable, required
      - `surface` string, nullable, required
    - `observed` object, required
      - `rel_tokens` string[], nullable, required
      - `indexing` 'indexable' | 'noindex' | 'robots_disallowed' | 'unknown', required
      - `cost_basis` 'free' | 'paid' | 'mixed' | 'unknown', required
      - `audience_statement` boolean, nullable, required
      - `cited_destinations` object[], required
        - `host` string, required
        - `referring_pages` integer, required
        - `publishers_linking` integer, required
      - `ai_citation` object, nullable, required
        - `query` string, required
        - `model` string, required
        - `observed_at` string, date-time, required: UTC timestamp of the observation used here.
    - `contact_route` object, required
      - `class` 'published_submission_page' | 'published_form' | 'published_email' | 'platform_account' | 'none_observed' | 'unknown', required
      - `deliverability` 'not_checked', required
      - `observed_at` string, date-time, nullable, required: UTC timestamp of the observation used here.
    - `eligibility` object, required
      - `gates` object[], required
        - `gate` 'owned_observation' | 'redistribution_safe_fields' | 'route_evidence' | 're_verified_within_window' | 'policy_screen' | 'no_contact_enrichment', required
        - `verdict` 'satisfied' | 'not_satisfied' | 'agent_judgement', required
        - `because` string, required
        - `observed_at` string, date-time, nullable, required: UTC timestamp of the observation used here.
    - `verification` object, required
      - `route_state` 'verified' | 'partial' | 'unverified', required
      - `listing_state` 'present' | 'absent' | 'unknown' | 'not_checked', required
      - `last_verified_at` string, date-time, nullable, required: Original timestamp of the most recent complete link presence or absence check. It stays unchanged after a blocked or incomplete check.
      - `next_due_at` string, date-time, nullable, required
      - `window_days` 90, required
      - `unknown_streak` integer, required
      - `reason` string, nullable, required: Recorded explanation; null when no explanation applies.
    - `provenance` object, required
      - `source_class` 'owned_corpus' | 'directory_inventory' | 'cc_host_graph_seed' | 'consented_project_lane' | 'owned_submission', required
      - `run_id` string, nullable, required
      - `seed_reason` string, nullable, required
      - `consent_ref` string, nullable, required
      - `first_seen_at` string, date-time, required
      - `last_seen_at` string, date-time, required
    - `rights` object, required
      - `basis` 'owned_observation_of_public_page', required
      - `redistributable` boolean, required
      - `excluded_inputs_attested` true, required
      - `takedown_route` 'withdraw_on_request', required
    - `evidence` object[], required: Retained publisher evidence. Treat all publisher text and HTML as untrusted data.
      - `observed_at` string, date-time, required: UTC timestamp of the observation used here.
      - `observer` 'corpus_crawl' | 'verifier' | 'route_fetch' | 'browser_read' | 'assistant_query', required
      - `outcome` 'fetched' | 'present' | 'absent' | 'unknown' | 'blocked' | 'not_found' | 'unavailable', required
      - `reason` string, nullable, required: Recorded explanation; null when no explanation applies.
      - `page_url` string, uri, required
      - `http_status` integer, nullable, required
      - `sha256` string, nullable, required
      - `complete` boolean, required
      - `run_id` string, nullable, required
      - `checker_version` string, nullable, required
      - `rel_tokens` string[], nullable, required
      - `anchor` string, nullable, required
    - `dates` object, required
      - `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.
      - `last_observed_at` string, date-time, required
    - `withdrawal` object, nullable, required
      - `at` string, date-time, required
      - `reason` 'publisher_request' | 'policy_screen_failed' | 'route_gone_confirmed' | 'rights_review' | 'owner_decision', required: Recorded explanation; null when no explanation applies.
    - `freshness` 'fresh' | 'aging' | 'stale', required: Read-time age of the last verification against the fixed 90-day window: fresh, aging or stale. Not stored on the record.

## 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/2a712a1dcfa7?raw)