Get a task & result

Read task progress and retrieve content when it is ready.

01 / Request

Make a request

GET/api/v1/scraping/tasks/{id}

Fetch the saved task ID with the same account that created it. Wait at least 6 seconds between progress checks. This request reads the task; it does not create or resubmit it.

Only use content when task.status is ready. Save it before contentExpiresAt. Stop polling on failed, review or expired; use the task lifecycle guide for the next action.

Required headers

AuthorizationstringRequired: Bearer followed by your ScrapingBuddy customer API key.

Path parameters

idUUID v4Required: The saved task ID, also the original Idempotency-Key. Invalid, unknown and other-account IDs return 404.

GET /scraping/tasks/{id}

curl --fail-with-body -X GET "https://www.scrapingbuddy.com/api/v1/scraping/tasks/$SCRAPINGBUDDY_TASK_ID" \
  -H "Authorization: Bearer $SCRAPINGBUDDY_API_KEY"

GET /scraping/tasks/{id}

const apiKey = process.env.SCRAPINGBUDDY_API_KEY;
const taskId = process.env.SCRAPINGBUDDY_TASK_ID;
if (!apiKey || !taskId) {
  throw new Error("Set the required environment variables before running.");
}

const response = await fetch(`https://www.scrapingbuddy.com/api/v1/scraping/tasks/${encodeURIComponent(taskId)}`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${apiKey}`
  }
});
const data = await response.json();
if (!response.ok) {
  throw new Error(`${response.status}: ${data.error}`);
}
console.log(data);

GET /scraping/tasks/{id}

import os
import requests
from urllib.parse import quote

api_key = os.environ["SCRAPINGBUDDY_API_KEY"]
task_id = quote(os.environ["SCRAPINGBUDDY_TASK_ID"], safe="")
response = requests.get(
    f"https://www.scrapingbuddy.com/api/v1/scraping/tasks/{task_id}",
    headers={
        "Authorization": f"Bearer {api_key}"
    },
    timeout=30,
)
data = response.json()
if not response.ok:
    raise RuntimeError(f"{response.status_code}: {data.get('error')}")
print(data)

Base URL https://www.scrapingbuddy.com/api/v1

Set SCRAPINGBUDDY_API_KEY and SCRAPINGBUDDY_TASK_ID in your server environment. JavaScript uses Node.js 20+; Python requires requests. These examples call the live, billed API.

02 / Response

Understand the response

Success returns HTTP 200 with JSON. A successful API response is not proof of successful page collection.

taskobject: The task object described below. Inspect task.status before reading content.

Task object

idUUID v4: The task ID is the Idempotency-Key you supplied when creating this task. Save it for result retrieval and support.
statusstring: queued, submitting, processing, researching, analyzing, ready, failed, review, or expired. An HTTP 200 alone does not mean the content is ready.
urlstring: The normalized source URL. URL fragments are removed.
formathtml | markdown: The requested content format. Defaults to html.
httpStatusinteger | null: The source website HTTP status, when available. This is separate from the status of your API request.
warningstring | null: A warning can accompany ready content when the wait condition was not met. Check whether the returned page is complete.
contentstring (conditional): Present only for a ready, unexpired task in create/get responses. Always omitted from task history. Save it before contentExpiresAt; do not execute returned HTML.
analysisobject (conditional): Present only when requested. status is pending, processing, ready, failed, skipped, or expired. A ready analysis contains result (summary, findings, limitations, sourceUrl), model, usage (inputTokens/outputTokens), and inputTruncated. With analysis.choices, it also contains decision: status, label, confidence, probabilities and insufficientEvidenceProbability. A failed analysis contains error.code and error.message; collected content is still returned. History exposes only analysis.status.
researchobject (conditional): Deep analysis only: maxPages, pagesCollected, pagesAttempted, stopReason and sources. stopReason is null, page_limit, links_exhausted, time_limit, unconfirmed_page, budget_exhausted or billing_review. Sources include URL, title, status, errorCode and warning; history returns sources: []. When available, webSearch reports status, sourcesFound and warning. content contains only the starting page, not all source pages.
errorobject | null: A task failure or review has code and message fields. This differs from the top-level error string returned for an unsuccessful API request.
billingobject: New paid tasks use mode: "usage". customerChargeUsd is the settled USD charge; heldUsd is a temporary wallet hold, not an additional charge. Provider costs are multiplied by 1.5. Earlier pilot tasks remain free.
createdAtISO timestamp: When the task was created.
completedAtISO timestamp | null: When processing finished, if available.
contentExpiresAtISO timestamp | null: Content and analysis expire 24 hours after page collection. After expiry, both results are omitted and status becomes expired.

Example response / illustrative values

{
  "task": {
    "id": "f824e030-0e09-4d70-a372-fdfd22e84721",
    "status": "ready",
    "url": "https://public-domain.example/about",
    "format": "markdown",
    "httpStatus": 200,
    "warning": null,
    "content": "# Example company\n\nPublic information from the public page.",
    "error": null,
    "billing": {
      "mode": "usage",
      "customerChargeUsd": "0.000450000",
      "heldUsd": "0.000000000"
    },
    "createdAt": "2026-10-08T10:00:00.000Z",
    "completedAt": "2026-10-08T10:00:12.000Z",
    "contentExpiresAt": "2026-10-09T10:00:12.000Z"
  }
}

URLs, IDs, costs, content and timestamps are illustrative. Use your own public hostname.

Errors & next steps

Request errors return an HTTP error status and a top-level error string. Processing failures appear in task.error even when fetching the result succeeds.

New tasks and batches require $1 available balance; insufficient starting credit returns 402. All customer keys share 60 requests per minute per account. For 429, honor Retry-After; active-task and daily limits may require a longer wait.

Errors & limits Safe retries Task lifecycle