# Embeddings API

Turn texts into embedding vectors with the model you pick (OpenAI, Google Gemini, Cohere, Voyage, Qwen and more) for search, clustering and RAG: one row per text with the vector, its size, the tokens it used, the exact model version, its maker and its exact share of the call's cost. You pay exactly what each call costs at the model's own token rate.

**Pricing:** Metered: you pay exactly each call's cost at the selected model's rates (default OpenAI: Text Embedding 3 Small: $0.02 per 1M input tokens). Each model's rates are listed with the `model` parameter's options in the API schema.

**Endpoint:** `POST /v1/data/ai/embeddings/run`

**Auth:** `Authorization: Bearer mk_live_...`

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `texts` | array | Yes | The texts to embed, one row per text (up to 100,000 characters each). |
| `model` | string | No | The embedding model. Pick from the list (popular models first). Each model shows its own rate per 1M input tokens, and that is exactly what each call costs. |
| `dimensions` | integer | No | The vector size, for models that support choosing it (OpenAI text-embedding-3, Gemini, Cohere Embed 5, Voyage 4, Qwen3 and others). Leave empty for the model's native size. |

## Example

`?wait=true` holds the request open until the run finishes (up to 60s) and returns the rows inline: one request, no polling.

```bash
curl -X POST "https://api.mindcase.co/v1/data/ai/embeddings/run?wait=true" \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"params":{"texts":["..."]}}'
```

```python
import requests

resp = requests.post(
    "https://api.mindcase.co/v1/data/ai/embeddings/run",
    params={"wait": "true"},
    headers={"Authorization": "Bearer mk_live_YOUR_API_KEY"},
    json={"params": {
    "texts": [
        "..."
    ]
}},
)
rows = resp.json()["data"]
```

## Longer runs

If the run is still going at the 60s ceiling you get back `{ job_id, status: "running" }` instead of rows (same if the result is over 100 rows; those come back `truncated`). Poll with that `job_id`:

```bash
# 1) check status
curl https://api.mindcase.co/v1/jobs/JOB_ID \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY"

# 2) when status == completed, fetch the rows
curl https://api.mindcase.co/v1/jobs/JOB_ID/results \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY"
```

Full API reference (auth, jobs, balance, SDKs, MCP): https://mindcase.co/skills.md

## Response columns

| Field | Display name | Type |
|-------|--------------|------|
| `id` | ID | text |
| `text` | Text | text |
| `embedding` | Embedding | array |
| `dimensions` | Dimensions | number |
| `tokens` | Tokens | number |
| `model` | Model | text |
| `provider` | Provider | text |
| `costUsd` | Cost (USD) | number |
| `error` | Error | text |
| `createdAt` | Created At | datetime |
