> ## Documentation Index
> Fetch the complete documentation index at: https://docs.llmlayer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Extract API

> Extract structured data, summaries, answers, links, and brand profiles from a single web page.

## Overview

Use Extract when you need one page transformed into application-ready data. A single request can combine modes, sharing the same page fetch:

| Mode | Response field | Requires LLM | Cost |
| - | - | -: | -: |
| `json` | `structured_data` | Yes | `$0.005` |
| `summary` | `summary` | Yes | `$0.005` |
| `qa` | `answer` | Yes | `$0.005` |
| `links` | `links` | No | `$0.001` |
| `brand` | `brand` | No | `$0.002` |

All result fields are present on every response. Modes you did not request are `null`.

## Endpoint

`POST /api/v2/extract`

## Quickstart: Structured Data

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { LLMLayerClient } from 'llmlayer';

  const client = new LLMLayerClient({
    apiKey: process.env.LLMLAYER_API_KEY,
  });

  const program = await client.extract('https://www.ycombinator.com/about', {
    modes: ['json'],
    jsonSchema: {
      program: 'string',
      duration: 'string',
      funding: 'string',
      benefits: ['string'],
    },
    instructions: 'Return concise values and use null when a field is missing.',
  });

  console.log(program.structured_data);
  console.log(program.summary); // null
  ```

  ```python Python theme={null}
  from llmlayer import LLMLayerClient

  client = LLMLayerClient(api_key="YOUR_LLMLAYER_API_KEY")

  program = client.extract(
      "https://www.ycombinator.com/about",
      modes=["json"],
      json_schema={
          "program": "string",
          "duration": "string",
          "funding": "string",
          "benefits": ["string"],
      },
      instructions="Return concise values and use null when a field is missing.",
  )

  print(program.structured_data)
  print(program.summary)  # None
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.llmlayer.dev/api/v2/extract \
    -H "Authorization: Bearer YOUR_LLMLAYER_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://www.ycombinator.com/about",
      "modes": ["json"],
      "json_schema": {
        "program": "string",
        "duration": "string",
        "funding": "string",
        "benefits": ["string"]
      },
      "instructions": "Return concise values and use null when a field is missing."
    }'
  ```
</CodeGroup>

## Request Parameters

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `url` | `string` | Yes | - | Public `http` or `https` page URL |
| `modes` | `string[]` | No | `["json"]` | Any of `json`, `summary`, `qa`, `links`, `brand` |
| `json_schema` | `object \| string` | Conditional | `null` | Required when `modes` includes `json` |
| `query` | `string` | Conditional | `null` | Required when `modes` includes `qa` |
| `instructions` | `string` | No | `null` | Extra guidance for LLM modes: `json`, `summary`, `qa` |
| `response_language` | `string` | No | `auto` | Best for summary and Q\&A text |
| `advanced_proxy` | `boolean` | No | `false` | Use for heavily protected pages |
| `main_content_only` | `boolean \| null` | No | API-selected | Omit to let the API choose the best mode-specific default |

<Note>
  HTTP requests use `snake_case`. The TypeScript SDK uses `camelCase`, for example `jsonSchema`, `responseLanguage`, and `advancedProxy`.
</Note>

## Response

```json theme={null}
{
  "url": "https://www.ycombinator.com/about",
  "title": "What Happens at YC | Y Combinator",
  "metadata": {
    "description": "..."
  },
  "structured_data": {
    "program": "Y Combinator startup program",
    "duration": "3 months",
    "funding": "$500k per company",
    "benefits": ["office hours", "founder community", "Demo Day"]
  },
  "summary": null,
  "answer": null,
  "links": null,
  "brand": null,
  "cost": 0.005,
  "response_time": "3.42",
  "statusCode": 200
}
```

| Field | Type | Description |
| - | - | - |
| `url` | `string` | Final URL after redirects |
| `title` | `string \| null` | Page title |
| `metadata` | `object \| null` | Page metadata found by the scraper |
| `structured_data` | `object \| null` | Result of `json` mode |
| `summary` | `string \| null` | Result of `summary` mode |
| `answer` | `string \| null` | Result of `qa` mode |
| `links` | `array \| null` | Result of `links` mode |
| `brand` | `object \| null` | Result of `brand` mode |
| `cost` | `number \| null` | Total cost for selected modes |
| `response_time` | `string` | Total processing time in seconds |
| `statusCode` | `integer` | `200` on success |

<Warning>
  The structured result field is `structured_data` in the API, Python SDK, and TypeScript SDK.
</Warning>

## Combining Modes

```python theme={null}
profile = client.extract(
    "https://www.ycombinator.com",
    modes=["summary", "links", "brand"],
)

print(profile.summary)
print(profile.links)
print(profile.brand)
```

```typescript theme={null}
const profile = await client.extract('https://www.ycombinator.com', {
  modes: ['summary', 'links', 'brand'],
});

console.log(profile.summary);
console.log(profile.links);
console.log(profile.brand);
```

## JSON Schema Guidance

`json_schema` can be:

* A formal JSON schema
* An example object
* A plain object where values describe expected types
* A plain-text description

For reliable extraction:

* Keep schemas focused.
* Use arrays only when the page clearly contains lists.
* Put normalization rules in `instructions`.
* Use nullable expectations when fields may be missing.

## Errors and Refunds

| Status | Common reason | Charged? |
| - | - | - |
| `400` | Missing `json_schema`, missing `query`, invalid mode, PDF URL | No |
| `422` | Empty extractable content, or JSON output truncated | Depends on whether AI work ran |
| `500` | Page fetch failed | Refunded when failure happens before AI work |
| `502` | Brand fetch or model JSON failure | Depends on failure stage |

See [Errors & Refunds](/errors) for exact error codes and refund behavior.

## More Examples

<CardGroup cols={2}>
  <Card title="Extract Recipes" icon="code" href="/examples/extract">
    Products, lists, Q\&A, and brand enrichment.
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/endpoint/extract">
    Full request and response schema.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.