Common questions, direct answers.

Do I need an account to use Quorel?

No. Every public dataset is accessible via GET request with no account, no API key, and no signup. You only need an account to create your own datasets, access private datasets, or use MCP.

How long does it take for my first dataset to be ready?

Usually a few minutes. Once you submit, Quorel crawls your URLs, runs AI extraction against your schema, and creates v1. You will receive a notification when it is done. Larger datasets with many URLs take longer.

Can I try Quorel without a credit card?

Yes. The Free plan requires no credit card and gives you one dataset with up to 20 URLs and 10 SERP-discovered URLs. You can hit the API, download data, use MCP, and roll back versions — all for free.

What kinds of websites can Quorel crawl?

Any publicly accessible web page. Quorel cannot crawl pages that require login, are behind paywalls, or actively block automated access. Reddit is supported natively via the Reddit JSON API. Amazon products are supported via a dedicated Amazon integration.

What happens if my schema doesn't match what's on the page?

The AI extractor does its best to map page content to your schema. Fields that cannot be found are returned as null. If you're getting too many nulls, try making your field descriptions more specific — the more context you give, the better the extraction.

Can I change my schema after the dataset is created?

Yes. Edit the schema from your dashboard. If the schema changes, any URLs with cached crawl data are automatically re-queued for re-extraction against the new schema. A new version is created when re-extraction completes.

Can I add or remove URLs after the dataset is created?

Yes. You can add new URLs or delete existing ones from the edit page in your dashboard. New URLs are queued immediately. Deleted URLs are removed from future refreshes but do not affect existing versions.

What is the extract intent and how is it different from the SERP intent?

The SERP intent is used to discover source URLs via web search — it answers the question 'where should Quorel look?'. The extract intent tells the AI what to extract from those pages — it answers 'what do you want from each page?'. Both are plain English. The extract intent must be at least 20 characters.

Why can't I edit my dataset right now?

Edits are blocked while a refresh is in progress. Wait for the current refresh to complete, then try again. You can check the status of each URL in your dashboard.

What does freezing a dataset do?

Freezing locks the dataset permanently at its current active version. No future refreshes will run. The API endpoint stays live and returns the frozen version indefinitely. Frozen datasets do not count against your plan's active dataset limit. Freeze is irreversible — clone the dataset first if you want an active copy.

Can I rename a dataset?

You can set an alias for your dataset from the edit page. The alias becomes the display name and the name-slug used in API URLs. The original internal name is preserved in the database but the alias takes precedence everywhere it is shown.

What is the difference between active, latest, and vN in the API URL?

active is the pinned version you control — it only changes when a new refresh completes or when you manually roll back. latest is always the highest version number. vN is an immutable reference to a specific version. For production consumers, always use active so you control when breaking changes land.

My request returned 404 even though the dataset ID is correct.

The name slug in the URL must match the dataset's display name exactly, lowercased and hyphenated. If you set an alias, the slug is derived from the alias, not the original name. Double-check the slug against what appears in your dashboard.

I'm getting 429 rate limit errors. What should I do?

Public requests are limited to 100 per minute per IP. Authenticated private requests get 300 per minute. Check the X-RateLimit-Reset header for when the window resets and the Retry-After header for how many seconds to wait. If you need higher limits, consider upgrading your plan.

Can I download data instead of hitting the API?

Yes. Every version is downloadable from the dashboard in JSON, CSV, JSONL, XML, TSV, or Parquet format. You can also add format=csv (or any other format) to your API request and the response will include a Content-Disposition header for direct download.

Does the API support pagination?

Yes. Use offset and limit query parameters. For example, offset=100&limit=50 returns entities 101–150. The X-Total-Count response header tells you how many entities matched after all filters were applied, so you can calculate total pages.

Can I filter on nested fields?

Yes. Both filter and filter_contains support dot-notation. For example, filter=author.location:london filters entities where the author object has a location field equal to 'london'. Filtering fans out across arrays — filter=reviews.rating:5 matches any entity where at least one review has a rating of 5.

Can I accidentally lose data by rolling back?

No. Rolling back only moves the active pointer — it does not delete any version. Every version ever created is permanently stored and accessible by its version number. You can roll forward again at any time.

What is an alt version and when would I use one?

An alt version is a separate copy of the entities for a given version that lives alongside the original without replacing it. Use it when you want to publish a cleaned, deduplicated, or enriched version of the data without touching the raw source. Alts can be created manually in the dashboard, via the API, or automatically by an MCP agent using push_alt_version.

Does cloning copy version history?

No. A clone starts fresh at v1, which contains a copy of the source dataset's latest version at the time of cloning. The clone's version history is fully independent from that point on. Future refreshes of the source do not affect your clone.

How does the diff work for modified entities?

Quorel matches entities across versions using their source URL and a weighted field-similarity score. Fields with more unique values across the dataset carry more weight. Two entities need a similarity score of at least 0.3 to be considered a match — below that threshold, they are treated as independent additions and subtractions rather than a modification.

What can Claude actually do with my datasets via MCP?

Claude can list your datasets, inspect their schemas, query with filters and keywords, pull the full entity list for processing, and push a cleaned version back as an alt. In practice this means you can ask Claude to deduplicate entries, fill missing fields, filter by complex criteria, summarize trends, or restructure data — all conversationally without writing code.

Does push_alt_version overwrite my original data?

Never. push_alt_version always writes to the alt path for that version. The original version file is never modified. If you push an alt and then delete it, the original is exactly as it was.

What happens if I generate a new MCP token?

Generating a new token immediately invalidates the old one. Any agent or Claude Desktop instance using the old token will be rejected on its next request. Update your claude_desktop_config.json with the new token URL after regenerating.

Is MCP available on the Free plan?

Yes. MCP access is included on every plan, including Free. You can connect Claude Desktop to your Free dataset and use all five tools.

What counts as an active dataset for plan limits?

Any dataset you own that is not frozen. Frozen datasets are excluded from the count. This means you can freeze datasets you are not actively using to stay within your plan limit without deleting them.

What happens if I hit my dataset or URL limit?

Creating a new dataset or adding URLs beyond your plan limit returns a 403 with a clear error message. Existing datasets and data are unaffected. Upgrade your plan to unlock more.

Can I clone a premium marketplace dataset on the Free plan?

Yes, if you have room in your dataset limit. Cloning a premium dataset requires a one-time payment per dataset. The payment reference is validated before the clone is created. Once cloned, it counts as one of your plan's datasets.

If I downgrade my plan, what happens to my datasets over the new limit?

Existing datasets are not automatically deleted. You will just be unable to create new ones until you are back within the limit. Freeze any datasets you are not actively using to free up slots without losing data.

Does the ping URL count toward my API rate limit?

No. The ping URL triggers a refresh internally and is not part of the dataset API. It is available on Pro and Scale plans only. Hitting the ping URL on a Free plan returns 403.

Can other users see my private dataset?

No. Private datasets do not appear in the marketplace and cannot be cloned. API requests to a private dataset without a valid Bearer token return 401. Only you can access it.

What is the _source field?

Every entity has a _source field containing the URL of the page it was extracted from. It is included by default and can be removed with include_source=false in the API request or drop_field=_source.

Can I delete my dataset and all its data?

Yes. Deleting a dataset from the dashboard permanently removes all versions, all alt files, the schema, all source URLs, and the queue records. This action is irreversible. You will receive an email confirmation when the deletion completes.