Getting Started

Parsium extracts structured data from webpages. Use a prebuilt endpoint for a supported platform, or create a custom parser for any other page.

Get an API key

Sign up at parseium.com.
Open API Keys in the dashboard.
Create a key and store it securely.

Authenticate

Send the key in X-API-Key (recommended). The api_key query parameter also works, but can leak through URLs and logs.

curl -H "X-API-Key: your_key" https://api.parseium.com/credits

{
  "creditBalance": 4850,
  "concurrency": 5,
  "fetchConcurrency": 5,
  "browserConcurrency": 2
}

creditBalance can be null before an account has ever been billed. For reserved credits, queue activity, and separate fetch/browser usage, use GET /v1/status instead.

Call a prebuilt API

Every prebuilt accepts query parameters with GET or the same field names as a POST JSON body. Calls cost 1 credit.

curl -H "X-API-Key: your_key" \
  "https://api.parseium.com/v1/instagram-profile?username=natgeo"

curl -X POST https://api.parseium.com/v1/instagram-profile \
  -H "X-API-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{"username":"natgeo"}'

Discover the current catalog with unauthenticated GET /v1/apis, then retrieve an endpoint’s parameters and response schema as Markdown from GET /v1/apis/{id}.

Scrape with a parser

After creating a parser in the dashboard or through POST /v1/parsers:

const response = await fetch(
  "https://api.parseium.com/v1/scrape/p_your_parser?url=https://example.com",
  { headers: { "X-API-Key": process.env.PARSIUM_API_KEY! } },
);
const data = await response.json();

Use POST /v1/parsers/test before saving or updating a parser. It validates selectors against the same fetch path used in production.

Run work asynchronously

Set async=1 on a scrape, or submit many parser URLs/prebuilt inputs to POST /v1/batches. The API returns job and batch IDs to poll. Batches over 100 items require a database sink.

curl -X POST https://api.parseium.com/v1/scrape/p_your_parser \
  -H "X-API-Key: your_key" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","async":true}'

{ "job_id": "j_…", "batch_id": "b_…" }

See Batches and jobs for polling and cancellation. Agents can also connect through MCP.

Handle errors

CRUD, queue, and database endpoints use this envelope:

{ "error": "invalid selector", "field": "price", "detail": "…", "hint": "…" }

Only error is guaranteed. Two important limit responses are:

{ "error": "insufficient credits", "required": 50, "available": 20 }

{ "error": "pending limit", "pending": 1000, "limit": 1000, "accepted": 0 }

Code	Meaning
400	Malformed JSON/request; parse/scrape may also report malformed HTML
401	Missing or invalid API key
402	Insufficient credits
404	Missing or not owned parser, job, batch, cron, workflow, or database
413	Legacy HTML upload exceeds 16 MB
422	Invalid config, URL, sink, batch, SQL, or unsupported upstream content
429	Request rate, concurrency, pending-job, or plan resource limit
502	Target fetch or upstream provider failed
503	A backing feature (for example datasets) is not configured or temporarily unavailable

Read Errors for retry guidance and structured upstream codes.