History

GET https://v2-api.scrapegraphai.com/api/history
GET https://v2-api.scrapegraphai.com/api/history/:id

History stores every API call your account makes (scrape, extract, search, monitor ticks, crawl jobs, schema generations) and lets you fetch them back later by ID. For crawl page content, use GET /api/crawl/:id/pages first; it returns paginated crawl pages with the underlying scrape result resolved into each page. Use History when you need to inspect an individual underlying request by its scrapeRefId.

List history

GET https://v2-api.scrapegraphai.com/api/history

Returns a paginated list of recent entries, newest first.

Query parameters

integer

default:"1"

Page number to fetch (1-indexed).

integer

default:"20"

Entries per page.

string

Filter by service. One of "scrape", "extract", "search", "monitor", "crawl", "schema".

string

Filter by session ID using a case-insensitive partial match. For example, sessionId=import matches import-2026-09-15.

Example request

curl -X GET "https://v2-api.scrapegraphai.com/api/history?service=scrape&sessionId=import&limit=5" \
  -H "SGAI-APIKEY: $SGAI_API_KEY"

Example response

{
  "data": [
    {
      "id": "9701fc04-23de-4684-a48f-7e8fa287550b",
      "userId": "4406e370-2405-4927-b7b3-b85c0a769b63",
      "sessionId": "import-2026-09-15",
      "service": "scrape",
      "status": "completed",
      "params": {
        "url": "https://scrapegraphai.com/",
        "formats": [{ "mode": "normal", "type": "markdown" }]
      },
      "result": {
        "results": { "markdown": { "data": ["# ScrapeGraphAI..."] } },
        "metadata": { "contentType": "text/html" }
      },
      "error": null,
      "elapsedMs": 533,
      "requestParentId": "06aa21dd-9a3a-417b-b2dd-0cd0943b7ded",
      "createdAt": "2026-04-28T09:00:02.907Z"
    }
  ],
  "pagination": { "page": 1, "limit": 5, "total": 178 }
}

Field	Description
`data[]`	Ordered list of history entries (newest first). See Entry shape.
`pagination.page` / `.limit`	Echo of the request’s `page` and `limit`.
`pagination.total`	Total entry count matching the filter (across all pages).

Get one entry

GET https://v2-api.scrapegraphai.com/api/history/:id

Returns the full record for a single request — including the full result payload (markdown, HTML, JSON extraction, screenshots, etc.).

Path parameters

string

required

The UUID of a request. This is the same UUID returned by the originating endpoint:

From POST /api/scrape → top-level id
From POST /api/extract → top-level id
From POST /api/search → top-level id
From GET /api/crawl/:id → each pages[].scrapeRefId
From GET /api/monitor/:cronId/activity → each ticks[].id

Example request

curl -X GET https://v2-api.scrapegraphai.com/api/history/9701fc04-23de-4684-a48f-7e8fa287550b \
  -H "SGAI-APIKEY: $SGAI_API_KEY"

Example response

{
  "id": "9701fc04-23de-4684-a48f-7e8fa287550b",
  "userId": "4406e370-2405-4927-b7b3-b85c0a769b63",
  "sessionId": "import-2026-09-15",
  "service": "scrape",
  "status": "completed",
  "params": {
    "url": "https://scrapegraphai.com/",
    "formats": [{ "mode": "normal", "type": "markdown" }]
  },
  "result": {
    "results": {
      "markdown": {
        "data": ["# ScrapeGraphAI\n\nThe scraper for the AI Era..."]
      }
    },
    "metadata": { "contentType": "text/html" }
  },
  "error": null,
  "elapsedMs": 533,
  "requestParentId": "06aa21dd-9a3a-417b-b2dd-0cd0943b7ded",
  "createdAt": "2026-04-28T09:00:02.907Z"
}

Entry shape

Every entry — both in GET /history and GET /history/:id — has the same shape:

Field	Description
`id`	Entry UUID. Same UUID as the originating endpoint returned.
`userId`	The account that issued the request.
`sessionId`	Optional request session from the `SGAI-Session-Id` header. `null` when the request did not include one.
`service`	`"scrape"` \| `"extract"` \| `"search"` \| `"monitor"` \| `"crawl"` \| `"schema"`.
`status`	Lifecycle: `"running"` \| `"completed"` \| `"failed"`.
`params`	The request body that produced this entry (URL, prompt, formats, etc.).
`result`	The full response payload, shaped per the originating endpoint. `null` while running, populated on completion.
`error`	Error object if `status === "failed"`, otherwise `null`.
`elapsedMs`	How long the request took, in milliseconds.
`requestParentId`	If this entry was created as a child of another (e.g. a scrape run by a crawl), the parent’s UUID. `null` for top-level requests.
`createdAt`	ISO-8601 timestamp.

Fetching crawled page content

The canonical pattern: start a crawl, poll until completed, then for each page fetch its scrape result.

# 1. Start the crawl
curl -X POST https://v2-api.scrapegraphai.com/api/crawl \
  -H "SGAI-APIKEY: $SGAI_API_KEY" \
  -H "SGAI-Session-Id: docs-crawl-1" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com", "formats": [{ "type": "markdown" }], "maxPages": 5 }'
# → { "id": "crawl-uuid", "status": "running", ... }

# 2. Poll status until completed
curl -X GET https://v2-api.scrapegraphai.com/api/crawl/crawl-uuid \
  -H "SGAI-APIKEY: $SGAI_API_KEY"
# → { "status": "completed", "pages": [{ "url": "...", "scrapeRefId": "page-uuid", ... }] }

# 3. Fetch each page's content via history
curl -X GET https://v2-api.scrapegraphai.com/api/history/page-uuid \
  -H "SGAI-APIKEY: $SGAI_API_KEY"
# → { "service": "scrape", "result": { "results": { "markdown": { "data": ["# ..."] } } }, ... }

The requestParentId on each child scrape entry equals the parent crawl’s id. Child entries also inherit the crawl request’s session ID, so you can list the workflow with:

curl -X GET "https://v2-api.scrapegraphai.com/api/history?service=scrape&sessionId=docs-crawl-1&limit=100" \
  -H "SGAI-APIKEY: $SGAI_API_KEY"

Errors

HTTP	`error.type`	When
`400`	`validation`	Malformed `id`, invalid `service`, or a `sessionId` longer than 128 characters.
`404`	`not_found`	The `id` is well-formed but no matching entry exists for this account.
`403`	`auth_invalid_key`	The API key is invalid or revoked.

See Error handling for the full envelope.

Crawl jobs that produce scrapeRefIds: Get crawl status
Originating endpoints whose id you can pass to GET /history/:id: Scrape, Extract, Search
SDK wrappers: sgai.history.list() and sgai.history.get(id) — see JavaScript SDK and Python SDK

API Documentation

Scrape

Extract

Search

Crawl

Monitor

Account

History

List history

Query parameters

Example request

Example response

Get one entry

Path parameters

Example request

Example response

Entry shape

Fetching crawled page content

Errors

​List history

​Query parameters

​Example request

​Example response

​Get one entry

​Path parameters

​Example request

​Example response

​Entry shape

​Fetching crawled page content

​Errors

​Related

List history

Query parameters

Example request

Example response

Get one entry

Path parameters

Example request

Example response

Entry shape

Fetching crawled page content

Errors

Related