---
title: "Read privacy-thresholded demand for the authenticated claim domain"
method: GET
path: "/provider/demand"
---

# Read privacy-thresholded demand for the authenticated claim domain

`GET /provider/demand`

Provider-key-authenticated read-only aggregate demand for the key's own current DNS-verified claim domain. The domain is derived from the authenticated claim and cannot be selected by the caller. Counts represent retained receipts, not unique agents or principals. Result-selection and action-interest counts and rates are suppressed below their exact receipt thresholds; topic and action-type rows are omitted below their thresholds. Organic-return counts and controlled surface labels remain reportable. No raw query, identity, contact, network data, alleged agent identity, or individual receipt is returned.

## Query parameters

- `days` integer

## Response `200`

Privacy-thresholded aggregate demand for the authenticated claim domain

- ProviderDemandResponse
  - `demand` ProviderDemandAnalytics, required
    - `domain` string, required — Domain derived from the authenticated provider claim; never caller-selected.
    - `days` integer, required
    - `retention_days` 30, required
    - `action_interest_cohort` 'organic_result_returned_at', required
    - `topic_receipt_threshold` 20, required
    - `result_selection_receipt_threshold` 20, required
    - `action_interest_receipt_threshold` 20, required
    - `synthetic_excluded` true, required
    - `summary` ProviderDemandSummary, required
      - `organic_results_returned` integer, required
      - `search_receipts` integer, required — Retained receipts
      - `average_organic_position` number, double, required
      - `result_selections` integer, nullable, required
      - `result_selection_rate` number, double, nullable, required
      - `result_selection_suppressed` boolean, required
      - `action_interest_receipts` integer, nullable, required
      - `action_interest_rate` number, double, nullable, required
      - `action_interest_suppressed` boolean, required
    - `surfaces` ProviderDemandSurface[], required
      - `surface` 'web' | 'rest' | 'mcp' | 'unknown', required
      - `organic_results_returned` integer, required
      - `result_selections` integer, nullable, required
      - `result_selection_suppressed` boolean, required
      - `action_interest_receipts` integer, nullable, required
      - `action_interest_suppressed` boolean, required
    - `demand_topics` ProviderDemandTopic[], required
      - `topic` 'payments' | 'commerce' | 'jobs' | 'data' | 'search' | 'weather' | 'maps' | 'email' | 'messaging' | 'image' | 'video' | 'audio' | 'documents' | 'security' | 'finance' | 'health' | 'education' | 'news' | 'analytics' | 'automation' | 'productivity' | 'identity' | 'storage' | 'ai-tools' | 'developer-tools' | 'other', required
      - `search_receipts` integer, required — Topic rows are omitted below the published privacy threshold.
      - `average_organic_position` number, double, required
      - `result_selections` integer, nullable, required
      - `result_selection_suppressed` boolean, required
      - `action_interest_receipts` integer, nullable, required
      - `action_interest_suppressed` boolean, required
    - `action_types` ProviderDemandActionType[], required
      - `action_type` 'quote' | 'trial' | 'demo' | 'booking' | 'application' | 'signup' | 'purchase', required
      - `receipt_count` integer, required — Action-type rows are omitted below the published privacy threshold.
  - `evidence_scope` string, required — Claim-scoped privacy-thresholded aggregates and explicit redaction boundary.

## Other responses

- `400` — Invalid days
- `401` — Valid active claim-scoped provider key required
- `404` — Authenticated claim is no longer verified and fresh
- `429` — Temporary provider read safety limit exceeded
- `500` — Provider demand query failed
- `503` — Provider key authentication unavailable

---

[API](https://skmtc.net/nothumansearch/apis/not-human-search-api.md) · [All operations](https://skmtc.net/nothumansearch/apis/not-human-search-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nothumansearch/not-human-search-api/revisions/a7faccfe4d5f/schema)