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

# Extract data

> Extract social, GitHub, or web page lists synchronously.

Submits an extraction request. The `type` selects the extractor, and `target` identifies the account, repository, or web page.

## Example

```bash theme={null}
curl "https://app.lev8.com/v1/extract" \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $LEV8_API_KEY" \
  --data '{
    "type": "x_followers",
    "target": "sama",
    "limit": 50
  }'
```

```bash theme={null}
curl "https://app.lev8.com/v1/extract" \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $LEV8_API_KEY" \
  --data '{
    "type": "web2list",
    "target": "https://example.com/directory",
    "instruction": "Extract company name, website, description, pricing tier",
    "limit": 20
  }'
```

## Response

```json theme={null}
{
  "success": true,
  "data": [
    {
      "username": "example_user"
    }
  ],
  "metadata": {
    "type": "x_followers",
    "target": "sama",
    "instruction": null,
    "limit": 50
  }
}
```

```json theme={null}
{
  "success": true,
  "data": [
    {
      "name": "Example Person",
      "company": "Example Co"
    }
  ],
  "metadata": {
    "type": "web2list",
    "target": "https://example.com/directory",
    "instruction": "Extract company name, website, description, pricing tier",
    "limit": 100
  }
}
```

For `web2list`, Lev8 requires `instruction`, accepts only a public HTTP or HTTPS URL in `target`, and always returns a normalized `metadata.limit` of `100`. Invalid input returns `422` through the standard error envelope before the extraction workflow starts.


## OpenAPI

````yaml POST /v1/extract
openapi: 3.1.0
info:
  title: lev8 API
  version: '1.0'
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
servers:
  - url: https://app.lev8.com
security:
  - ApiKeyAuth: []
paths:
  /v1/extract:
    post:
      summary: Extract data
      description: Extract social, GitHub, or web page lists synchronously.
      operationId: extractData
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          description: >-
            Optional stable key for this logical request. When omitted, lev8
            generates one and returns it in the response Header.
          schema:
            type: string
            maxLength: 128
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtractRequest'
            example:
              type: web2list
              target: https://www.forbes.com/30-under-30/2026/ai
              instruction: >-
                Extract all 30 Under 30 names, companies, and positions from the
                AI category list
              limit: 20
      responses:
        '200':
          description: Extracted data.
          headers:
            Idempotency-Key:
              description: The supplied or server-generated idempotency key.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractResponse'
        '401':
          description: Missing or invalid API key.
        '402':
          description: Insufficient credits.
        '403':
          description: API key is forbidden or lacks Extract access.
        '409':
          description: >-
            Idempotency conflict or no completed response is available to
            replay.
        '422':
          description: Validation failed.
        '429':
          description: Concurrency limit reached.
        '500':
          description: Server error.
        '503':
          description: Extract is not enabled.
components:
  schemas:
    ExtractRequest:
      type: object
      additionalProperties: false
      required:
        - type
        - target
      properties:
        type:
          type: string
          enum:
            - x_followers
            - x_following
            - github_user_followers
            - github_user_following
            - github_repo_stargazers
            - github_repo_contributors
            - ins_followers
            - ins_following
            - tiktok_followers
            - tiktok_following
            - web2list
          description: >-
            Extraction type. `web2list` extracts a structured list from a web
            page; the other values return social or GitHub lists.
          x-default: web2list
          example: web2list
        target:
          type: string
          minLength: 1
          maxLength: 2048
          description: >-
            Account handle, GitHub repository, repository URL, or web page URL
            to extract from.
          x-default: https://www.forbes.com/30-under-30/2026/ai
          example: https://www.forbes.com/30-under-30/2026/ai
        instruction:
          type:
            - string
            - 'null'
          maxLength: 4000
          description: >-
            Required for `web2list`. Describes the list items and fields to
            extract.
          x-default: >-
            Extract all 30 Under 30 names, companies, and positions from the AI
            category list
          example: >-
            Extract all 30 Under 30 names, companies, and positions from the AI
            category list
        limit:
          type: integer
          minimum: 1
          maximum: 10000
          default: 100
          description: >-
            Maximum number of social or GitHub list results. `web2list` ignores
            this field.
          x-default: 100
          example: 20
    ExtractResponse:
      type: object
      additionalProperties: false
      required:
        - success
        - data
        - metadata
      properties:
        success:
          type: boolean
          example: true
        data:
          description: >-
            Extracted list data on success, or a failure reason string when
            `success` is false.
          oneOf:
            - type: array
              items:
                type: object
                additionalProperties: true
            - type: string
          example:
            - name: Example Person
              company: Example Co
        metadata:
          $ref: '#/components/schemas/ExtractMetadata'
    ExtractMetadata:
      type: object
      properties:
        type: 4f0f5baf-c985-4817-9450-c828887fa952
        target:
          type: string
          example: https://www.forbes.com/30-under-30/2026/ai
        instruction:
          type:
            - string
            - 'null'
          example: Extract name and company
        limit:
          type: integer
          example: 100
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      x-default: lev8_live_...

````