Embeddings

Before You Start

Embeddings run on your own OpenAI API key. Add it once under Dashboard > Settings > LLM keys (see bring your own key). Without a registered key the request is rejected with 400 byok_key_required before anything is charged. AlterLab bills only a small add-on per page: +$0.001 (1,000 microcents) for each page that was actually embedded. The OpenAI usage itself goes to your OpenAI account.

Enable Embeddings on a Scrape

curl -X POST https://api.alterlab.io/api/v1/scrape \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/docs/getting-started",
    "embeddings": {
      "enabled": true,
      "model": "text-embedding-3-small",
      "chunk_size": 512,
      "chunk_overlap": 50
    }
  }'

embeddings is an add-on, not a format: the scrape still returns the formats you asked for. The same object works on batch items (POST /api/v1/batch) and on crawls.

Options

• enabled: set to true to generate embeddings. Default false.
• model: text-embedding-3-small (1,536 dimensions, cheapest, the default) or text-embedding-3-large (3,072 dimensions, best quality).
• chunk_size: target chunk size in tokens, 64 to 8,191. Default 512.
• chunk_overlap: tokens shared by neighboring chunks, 0 to 2,048 and always below chunk_size. Default 50.

Read the Result

The response adds an embeddings object with model, dimensions, total_chunks, total_tokens, cached and a chunks array. Each chunk holds its text, the embedding vector and the start_index and end_index character offsets in the page text, so you can map a hit back to its source.

{
  "embeddings": {
    "model": "text-embedding-3-small",
    "dimensions": 1536,
    "total_chunks": 3,
    "total_tokens": 1180,
    "cached": false,
    "chunks": [
      {"text": "Getting started with...", "embedding": [0.012, -0.034], "start_index": 0, "end_index": 1904}
    ]
  }
}

When Embeddings Fail

If your key is invalid, out of quota or OpenAI errors after the page was fetched, the scrape still succeeds. The response carries embeddings_error with a code (no_api_key, invalid_key, quota or provider_error) and a message, and the add-on is not charged.

Dashboard and Playground

The Embeddings console at /dashboard/embeddings runs the same request from the browser, then lets you explore the chunks, compare the vectors and export them. Use it to check chunk sizes on a real page before wiring it into a pipeline.

Related

Combine embeddings with crawling to index a whole site, and with structured extraction when you also need typed fields. All request fields are in the scrape reference.