--- title: "Extract" method: POST path: "/extract" --- # Extract `POST /extract` ## Request - Base URL: `https://api.octen.ai` - URL: `https://api.octen.ai/extract` - Auth: one of: - HTTP bearer - API key in header `x-api-key` Extracts clean markdown content from URLs. Supports batch processing, query-focused highlights, page classification, and multimedia resources. ## Request body - ExtractRequest: Request body for the Extract API. - `urls` string[], required: List of URLs to extract content from. Maximum URLs per request: 20. Maximum length per URL: 2048. Failed URLs are not billed. - `mode` 'standard' | 'advanced' | 'auto': Processing mode. `standard` prioritizes speed, `advanced` prioritizes success rate on hard-to-reach pages, and `auto` picks one per URL. `advanced` and `auto` can take longer, so raise `timeout` accordingly. - `query` string: Intent-focused keywords. When provided, returns query-relevant highlights per URL; otherwise returns the complete page content. - `max_age_seconds` integer: Maximum age (in seconds) of cached content. URLs whose cached version exceeds this threshold will be re-fetched. Values outside the allowed range are adjusted to the nearest bound. - `format` 'markdown' | 'text': Format of the returned content. - `timeout` integer: Per-URL extraction timeout in seconds. Values outside the allowed range are adjusted to the nearest bound. - `include_images` boolean: Whether to return image URLs detected on the page. - `include_videos` boolean: Whether to return video URLs detected on the page. - `include_audio` boolean: Whether to return audio URLs detected on the page. - `include_links` object: Controls whether to return links detected on the page. - `scope` 'prefer_internal' | 'prefer_external': Which links to prioritize. `prefer_internal` favors links within the page's registered domain; `prefer_external` favors external links. Prioritized links come first, and links of the same kind keep their order on the page. - `max_links` integer: Maximum number of links to return per URL. ## Response `200` Successful extraction response - ExtractResponse - `code` integer: Business status code. 0 indicates success. - `msg` string: A message describing the result. - `request_id` string: The unique identifier for this request. - `data` ExtractData: The main extract response payload. - `results` ExtractResult[]: Extraction result for each requested URL. Order matches the input urls array. - `url` string: The requested URL. - `status` 'success' | 'failed': Extraction status for this URL. - `resolved_mode` 'standard' | 'advanced': The mode this URL is billed at. For `auto`, the mode chosen for this URL. Returned when `status` is `success`. - `title` string, nullable: Page title, extracted from HTML `` or `<meta>` tags. - `full_content` string, nullable: Complete page content in the requested format. Returned when `query` is not provided. - `highlights` string[], nullable: Query-relevant snippets, sorted by relevance. Returned when `query` is provided. - `time_published` string, date-time, nullable: Content publication time, ISO 8601 format. - `time_last_crawled` string, date-time: Most recent time Octen crawled this URL, ISO 8601 format. - `page_structure` ExtractPageStructure: Detected page structure for an extraction result. - `primary` 'Index Page' | 'Content Page' | 'No Main Content': Top-level page type. - `secondary` string, nullable: Sub-type within the primary structure. 50+ possible values. `null` when no sub-type applies. - `category` ExtractCategory: Detected content category for an extraction result. - `primary` string: Top-level content category. 23 possible values. - `secondary` string, nullable: Sub-category within the primary category. 160+ possible values. `null` when no sub-category applies. - `favicon` string, nullable: The page's favicon URL. Returned by default when available. - `cover_image` object, nullable: The page cover image. Returned only when `include_images` is `true` and the page has a cover image. - `url` string: Image URL. - `images` ExtractMediaResource[]: Image resources detected on the page. Returned when `include_images` is `true` and the page contains images. - `url` string: Resource URL. - `videos` ExtractMediaResource[]: Video resources detected on the page. Returned when `include_videos` is `true` and the page contains videos. - `url` string: Resource URL. - `audio` ExtractMediaResource[]: Audio resources detected on the page. Returned when `include_audio` is `true` and the page contains audio. - `url` string: Resource URL. - `links` ExtractLink[]: Links detected on the page, deduplicated. Returned for successful results when `include_links` is set and links are detected on the page. - `url` string: Absolute URL of the link target. - `anchor_text` string: The link's visible text on the page. Empty when the link has no visible text. - `is_external` boolean: Whether the link points to a different registered domain than the page. - `error_message` string: Failure reason. Only present when `status` is `failed`. See the Error Codes reference for the complete list of result-level error messages. - `meta` ExtractMeta: Additional metadata for the extract request. - `usage` ExtractUsage: Usage and billing breakdown for the extract request. - `total_urls` integer: Total number of URLs in the request. - `successful_urls` integer: Number of successfully extracted URLs (billed). Failed URLs are not counted. - `successful_by_mode` object: Breakdown of successful URLs by `resolved_mode`. - `standard_urls` integer: Successful URLs billed at the standard rate. - `advanced_urls` integer: Successful URLs billed at the advanced rate. - `latency` integer: Total request latency in milliseconds. - `warning` string: Warning messages for the request, separated by semicolons. An empty string when there is nothing to report. ## Other responses - `400`: Invalid params — Returned when a required parameter is missing or invalid. - `401`: Invalid API Key — Returned when the API key is missing or invalid. - `403`: Insufficient balance in account — Returned when the account balance is insufficient to complete the request. - `429`: Exceeding the rate limit — Returned when the request exceeds the configured rate limit. - `500`: Internal error — Returned when an unexpected server-side error occurs. --- [API](https://skmtc.dev/octen/apis/octen-api.md) - [All operations](https://skmtc.dev/octen/apis/octen-api/llms.txt) - [OpenAPI document](https://skmtc.dev/octen/apis/octen-api/revisions/aaa6caaf46b0?raw)