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

# POST /v1/extract — AI Video Extraction

> Send a prompt to extract structured information from any video. Optionally enforce output shape with a JSON Schema. Costs 10 credits per job.

`/v1/extract` is an async AI operation that watches the whole video and returns a structured answer to your prompt. POST to enqueue the job, then poll until the result is ready. If you're using the MCP server, polling is handled automatically and your agent receives the finished result directly.

**Credits:** 10 credits per extraction.

***

## Step 1 — Enqueue the job

```
POST https://api.veedcrawl.com/v1/extract
```

This endpoint requires an `x-api-key` header and `Content-Type: application/json`.

### Body parameters

<ParamField body="url" type="string" required>
  The full public video URL, or a direct media file URL.
</ParamField>

<ParamField body="prompt" type="string" required>
  What to extract or analyze — for example: `"List all product names"`, `"Summarize in 3 sentences"`, or `"What is the hook?"`.
</ParamField>

<ParamField body="lang" type="string">
  Optional language hint for transcription — e.g. `"en"`, `"es"`, `"ur"`.
</ParamField>

<ParamField body="schema" type="object">
  Optional [JSON Schema](https://json-schema.org/) object that constrains the shape of `resultJson`. Use this to get typed, predictable output that slots directly into your application.
</ParamField>

### Example

```bash theme={null}
curl -X POST "https://api.veedcrawl.com/v1/extract" \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=...", "prompt": "Extract all product names shown"}'
```

### Response

```json theme={null}
{
  "jobId": "job_xyz456",
  "status": "queued"
}
```

***

## Step 2 — Poll for the result

```
GET https://api.veedcrawl.com/v1/extract/{jobId}
```

### Example

```bash theme={null}
curl "https://api.veedcrawl.com/v1/extract/job_xyz456" \
  -H "x-api-key: YOUR_KEY"
```

### Response when complete

```json theme={null}
{
  "jobId": "job_xyz456",
  "status": "completed",
  "resultJson": {
    "products": ["iPhone 16 Pro", "AirPods Pro 2"]
  }
}
```

Poll until `status` is `"completed"` or `"failed"`.

***

## Example prompts

The `prompt` field is free-form. Here are prompts that work well:

* `"Extract the hook, main argument, and call to action"`
* `"List every product mentioned with the timestamp it appears"`
* `"What claims does the speaker make? Rate each one as factual, opinion, or unverified"`
* `"Rewrite this as a Twitter thread"`

***

## Using JSON Schema for typed output

Pass a `schema` field to constrain the structure of `resultJson`. This is useful when you need the result to conform to a specific interface in your application.

```bash theme={null}
curl -X POST "https://api.veedcrawl.com/v1/extract" \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=...",
    "prompt": "List every product mentioned in the video",
    "schema": {
      "type": "object",
      "properties": {
        "products": {
          "type": "array",
          "items": { "type": "string" }
        }
      },
      "required": ["products"]
    }
  }'
```

<Note>
  If you're using the Veedcrawl MCP server, polling is handled automatically. Your agent receives the completed extraction result without any extra logic.
</Note>