Extract

Extract scrapes every URL you give it, then has a model fill in one merged JSON value that is validated against your schema. Every successful response conforms: no "almost JSON", no missing required keys. Give a schema, a prompt, or both. 15 credits per URL scraped successfully (+1 per page when scrapeOptions.actions runs). URLs that fail are free and listed in sources with an error code. If no valid JSON can be produced, the request fails with extract_failed at 0 credits.

Example#

curl -X POST "https://api.vermin.dev/v1/extract" \
  -H "Authorization: Bearer $VERMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/pricing"],
    "schema": {
      "type": "object",
      "properties": {
        "plans": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "monthlyUsd": { "type": "number" }
            },
            "required": ["name", "monthlyUsd"]
          }
        }
      },
      "required": ["plans"]
    },
    "prompt": "Every plan with its monthly price in USD"
  }'

Request#

Response#

{
  "success": true,
  "data": {
    "plans": [
      { "name": "Starter", "monthlyUsd": 19 },
      { "name": "Pro", "monthlyUsd": 89 }
    ]
  },
  "sources": [{ "url": "https://example.com/pricing", "ok": true }],
  "credits_used": 15,
  "request_id": "req_01J9V7D4NP"
}

Limits#

• Schemas up to 32 KB. $ref must point inside the schema (#/$defs/address) and can't be recursive. patterns are limited to 256 characters and can't nest quantifiers like (a+)+.
• Content: each request reads about 12,000 tokens of the pages, keeping the parts most relevant to your schema and prompt.
• Time: pages are scraped within 60 seconds and the whole request finishes within 150 seconds, or fails with timeout at 0 credits. Set your HTTP client's timeout above that; the SDKs already do.
• Failed extracts are free, but each organization gets a daily allowance of them (25 a day on Free, more on paid plans). Past it, extract answers rate_limited until midnight UTC. An allowance that runs out usually means the schema asks for something the pages don't have.
• Retries are safe with an Idempotency-Key header: a repeated key returns the first response without running or charging again.

Writing good schemas#

• Require only what must exist. Every required field the page doesn't have is a reason to fail. Optional fields come back when present.
• Describe fields. description on a property is passed to the model: "monthlyUsd": { "type": "number", "description": "Price per month, USD, before tax" }.
• Keep it flat-ish. Deeply nested schemas work, but a flat list of objects is faster and more accurate.
• Use prompt for judgement calls: "ignore enterprise plans", "prices in USD, convert if needed".