---
title: "Buy a list from the live web, paid per match"
method: POST
path: "/v1/agent/lists"
---

# Buy a list from the live web, paid per match

`POST /v1/agent/lists`

## Request

- Base URL: `https://api.specstream.ai`
- URL: `https://api.specstream.ai/v1/agent/lists`
- Auth: none declared

Without a payment this answers 402 with the most the run can cost. Pay with MPP or x402 and send the same request again to start the run.

## Request body

- object
  - `request` string, required: The list you need, in plain words.
  - `count` integer: How many matches to look for.

## Response `202`

Paid. The run has started; read status_url.

- object
  - `purchase_id` string, required
  - `token` string, required: Send as Authorization: Bearer <token> to read the purchase.
  - `status_url` string, uri, required
  - `read_with` string
  - `paid` string: Dollars charged by card, when paid by card.
  - `authorized` string: Dollars authorized in USDC, when paid over x402.
  - `currency` string
  - `reading` object
  - `find_id` string
  - `status` string
  - `note` string

## Other responses

- `402`: Payment Required
- `422`: The request wasn't a list in plain words, or count was outside 1 to 500
- `default`: Error envelope

---

[API](https://skmtc.dev/specstream/apis/specstream-api.md) · [All operations](https://skmtc.dev/specstream/apis/specstream-api/llms.txt) · [OpenAPI document](https://skmtc.dev/specstream/apis/specstream-api/revisions/5a9f51143a13?raw)