> ## Documentation Index > Fetch the complete documentation index at: https://docs.hydrafetch.com/llms.txt > Use this file to discover all available pages before exploring further. # Start a batch > Scrape an explicit list of URLs as one asynchronous job. Returns a batch id immediately; poll it or register a webhook. One credit per URL scraped. ## OpenAPI ````yaml https://api.hydrafetch.com/openapi.json post /v1/web/batch openapi: 3.0.0 info: title: Hydrafetch API description: >- Hydrafetch is a web data API for LLMs and agents. Send a URL and get back clean Markdown, the page's own structured data, schema-shaped JSON, links, or a summary, with the navigation, banners and boilerplate stripped out. Scrape one page, crawl a whole site, run a search, or extract to a schema, all through one API with one response shape. Every call costs one credit a page whatever it took to fetch, and failures are never billed. Point us at a whole site and get every page. Ask a question and get answers with per-field confidence and the passage each value came from. You describe the outcome you want — the pipeline decides how to get it. ## Authentication Every request is authenticated with your API key in the `X-API-Key` header. Keys are scoped to a workspace and carry its credit balance. ## Credits Calls are billed in credits and charged only on success. A standard scrape is one credit; richer formats and the extraction tier cost more. Each response reports what it consumed. ## Conventions All timestamps are UTC ISO 8601. Long-running jobs (crawl, batch) return a job id you poll, or a webhook you register. Errors return a structured body with a stable `code` and an HTTP status. version: '1.0' contact: name: Hydrafetch url: https://hydrafetch.com email: support@hydrafetch.com servers: - url: https://api.hydrafetch.com description: Production security: - apiKey: [] tags: - name: Scrape description: >- Turn one URL into clean, LLM-ready content. Ask for Markdown, HTML, links, or the page’s own structured data, and poll a job id when a fetch runs long. - name: Crawl & batch description: >- Whole sites rather than single pages. Map every URL, crawl with depth and path rules, batch a list you already have, and read the webhook deliveries for either. - name: Search description: >- Search the web and get the ranked results back already scraped, so an agent has content to cite rather than links to fetch. - name: Extract description: >- Pull schema-shaped JSON out of one or many pages, with optional per-field confidence and the source passage behind each value. - name: Brand description: >- Resolve a domain into the company ready to render: logos for light and dark, the palette ranked by how the site uses it, fonts, socials, and the design system behind them. - name: Media description: >- Images and screenshots from a page, with source and alt text, or a rendered capture of the page as it appears. paths: /v1/web/batch: post: tags: - Crawl & batch summary: Start a batch description: >- Scrape an explicit list of URLs as one asynchronous job. Returns a batch id immediately; poll it or register a webhook. One credit per URL scraped. operationId: startBatch parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BatchRequestDto' responses: '201': description: The batch was accepted. content: application/json: schema: $ref: '#/components/schemas/BatchAcceptedDto' components: schemas: BatchRequestDto: type: object properties: urls: minItems: 1 maxItems: 1000 example: - https://example.com/a - https://example.com/b description: The explicit list of URLs to scrape. Each must be http(s). type: array items: type: string webhook: description: >- Register a callback to be notified as the batch progresses instead of polling. allOf: - $ref: '#/components/schemas/WebhookDto' scrapeOptions: description: How to scrape each URL. Same options as a single scrape. allOf: - $ref: '#/components/schemas/ScrapeOptionsDto' required: - urls BatchAcceptedDto: type: object properties: batchId: type: string example: 019f3c09-6fae-740f-9257-10c2b6af7f43 description: Poll this batch id for progress and results. status: type: string enum: - queued example: queued description: The job has been accepted. required: - batchId - status WebhookDto: type: object properties: url: type: string example: https://your-app.com/hooks/hydrafetch description: >- The URL to POST events to. Must be a public http(s) URL — private, loopback, and link-local addresses are rejected. events: type: array example: - page - completed description: >- Which events to receive. `page` fires as each page finishes; `completed` fires once when the job ends. Defaults to both. items: type: string enum: - page - completed headers: type: object additionalProperties: type: string example: Authorization: Bearer your-token description: Extra headers to send with each callback, e.g. for authentication. secret: type: string example: whsec_a_long_random_string minLength: 16 maxLength: 256 description: >- A shared secret. When set, each callback carries an X-Hydrafetch-Signature header you can verify to prove the request came from us and is not a replay. required: - url ScrapeOptionsDto: type: object properties: formats: type: array example: - markdown description: What to return per page. Omit for Markdown only. items: type: string enum: - markdown - html - rawHtml - links - structured onlyMainContent: type: boolean description: Return only the main content, dropping boilerplate. Default true. includeTags: maxItems: 50 description: CSS selectors to keep. type: array items: type: string excludeTags: maxItems: 50 description: CSS selectors to strip before extraction. type: array items: type: string removeBase64Images: type: boolean description: Strip inline base64 images. Default true. blockAds: type: boolean description: Remove common ad and tracking elements. Default true. includeLinks: type: boolean description: >- Keep inline links in the markdown. Default true — a bare `Read the guide` is worth less to a model than one it can follow. Turn off for the densest possible prose. renderJs: type: boolean description: Force full page rendering for JavaScript-heavy pages. waitFor: type: number minimum: 0 maximum: 30000 description: Extra milliseconds to let the page settle before capture. timeout: type: number minimum: 1000 maximum: 120000 description: Per-page time budget, in milliseconds. location: $ref: '#/components/schemas/OptLocationDto' headers: type: object additionalProperties: type: string description: Extra request headers to send when fetching each page. preferStructure: type: boolean description: Preserve document structure over prose density. Default off. maxAge: type: number minimum: 0 maximum: 604800000 description: Serve a page from cache if younger than this many milliseconds. OptLocationDto: type: object properties: country: type: string example: us description: ISO 3166 alpha-2 country to fetch as if from. languages: example: - en-US - en description: Preferred content languages, most-preferred first. type: array items: type: string securitySchemes: apiKey: type: apiKey in: header name: X-API-Key ````