Quickstart
Create a Dataset, run it, and read checked rows with the Grava API.
You need a Grava account, an API key, and curl. Sign in at app.grava.dev, open API keys, create a key, and copy it when it is shown.
1. Save your key
Keep the key out of shell history, source control, screenshots, and chat transcripts.
read -rsp "Grava API key: " GRAVA_API_KEY
export GRAVA_API_KEY
printf '\n'2. Create a Dataset
This example collects the Fiction category from Books to Scrape, a public scraping demo site. The selectors are declarative; Grava does not execute customer code.
curl --request POST "https://app.grava.dev/api/v1/datasets" \
--header "Authorization: Bearer $GRAVA_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"name": "Fiction books",
"columns": [
{ "name": "source_id", "type": "string", "key": true },
{ "name": "title", "type": "string" }
],
"source": {
"version": 1,
"url": "https://books.toscrape.com/catalogue/category/books/fiction_10/index.html",
"render": "static",
"itemSelector": "article.product_pod",
"fields": [
{ "name": "source_id", "read": { "selector": "h3 a", "kind": "attribute", "attribute": "href" }, "required": true },
{ "name": "title", "read": { "selector": "h3 a", "kind": "attribute", "attribute": "title" }, "required": true }
],
"identity": { "kind": "source-key", "field": "source_id" },
"pagination": { "kind": "next-link", "selector": ".next a" }
}
}'Each record is one book. The source link supplies stable identity, and each field is read inside that book’s container. Pagination follows the next link until it disappears; reaching a limit holds the Run without charging.
Save the dataset.id from the response as DATASET_ID.
3. Enqueue a Run
curl --request POST "https://app.grava.dev/api/v1/datasets/$DATASET_ID/runs" \
--header "Authorization: Bearer $GRAVA_API_KEY"The response is 202 Accepted and includes a runId. Poll GET /v1/runs/{runId} until its status is succeeded, failed, blocked, or held. Held output needs attention and does not replace accepted values.
4. Read the rows
curl "https://app.grava.dev/api/v1/datasets/$DATASET_ID/rows" \
--header "Authorization: Bearer $GRAVA_API_KEY"Row data is keyed by the stable Field IDs returned in the Dataset’s columns. Use a row’s detail endpoint to inspect evidence and /v1/datasets/{datasetId}/changes for durable history.
Every authenticated response includes X-Credits-Remaining. A passing Run costs one credit per page checked. A failed Check writes no rows and costs nothing.