---
title: "Extract clean rows from a public web page"
method: POST
path: "/v1/extract"
tags: ["Sources"]
---

# Extract clean rows from a public web page

`POST /v1/extract`

## Request

- Base URL: `https://www.licium.ai`
- URL: `https://www.licium.ai/v1/extract`
- Auth: HTTP bearer

Send a public, logged-out page URL and the columns you want. A Bearer API key is required; create a free key instantly with POST /v1/keys. A sample comes back first for any new source, so the rows can be checked before anything else.

## Request body

- object
  - `url` string, required: Public, logged-out page URL to extract from.
  - `fields` string[]: Column names you want back, e.g. ["title", "location", "url"].

## Response `200`

Rows extracted. An unverified empty result that is queued for coverage also includes the pot action or a machine-readable unavailability reason.

- ExtractRowsEnvelope
  - `success` true, required
  - `data` object, required
    - `rows` object[], required
    - `count` integer, required
    - `fields` string[], required
    - `source` string, uri, required
    - `verified_empty` boolean, required
    - `retrieved_at` string, date-time, required
  - `bounty_id` string, uuid
  - `pot_status` 'needs_fixtures' | 'open' | 'in_progress' | 'delivered': The pot's own state. needs_fixtures: the pot is on the board but takes no money and no finals until its opener freezes the contract and its example answers; until then the answer has pot_waiting instead of pledge_url.
  - `pot_contract_url` string, uri: Present only while the pot waits and only for the caller who can add its example answers without paying: the key that created the request.
  - `pot_open_url` string, uri: Present while the pot waits when anyone can open it (a request sent without a key): POST it with amount_usd and contract; the pot opens with that contract when the payment goes through.
  - `pot_waiting` PotWaiting: Present while the request's pot waits for its example answers (pot_status needs_fixtures). It takes no money and no deliveries until then, so there is no pledge_url.
    - `message` string, required
    - `added_by` 'you' | 'the requester' | 'the first person who puts money in' | 'Licium, or the first person who puts money in': Who adds the example answers. you: this caller can, without paying, at pot_contract_url. the first person who puts money in: anyone can open it at pot_open_url.
    - `next` string, required: What to do next: for a caller who can add them without paying, how (POST pot_contract_url or the MCP tool bounty_pot_contract); when anyone can open it, how (POST pot_open_url with amount_usd and contract, or bounty_pledge with contract); otherwise poll poll_url to see when it opens.
    - `poll_url` string, uri, required: GET the request: pot_status turns open and pledge_url appears once the pot takes money.
  - `pot` PotTotals
    - `funded_total_usd` integer, required
    - `funded_pledge_count` integer, required
    - `intent_count` integer, required
    - `counter_median_usd` number, nullable, required
    - `counter_count` integer, required
  - `pledge_url` string, uri: Present once the pot takes money.
  - `subscribe_url` string, uri
  - `pot_unavailable_reason` 'request_not_found' | 'request_not_queued' | 'caller_cap_reached' | 'board_cap_reached' | 'temporarily_unavailable' | 'not_machine_checkable': not_machine_checkable: no automatic check can decide the result (no named content fields, or the request text or field names ask for judgment), so no pot opens. Post a bounty with a fixed reward at post_bounty_url instead. This guard applies only to new pots; existing pots keep their original rules.
  - `escalate_url` string, uri
  - `post_bounty_url` string, uri

## Other responses

- `202`: The page is not covered yet. It was queued without billing, and the response includes the pot action or a machine-readable unavailability reason.
- `401`: Missing or invalid Bearer API key.
- `429`: Rate limit or daily quota exceeded.

---

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