Skip to main content

Embedding Playground and Search

An embedding project has two ways to try a public base or hosted embedding model before you build on it: the Playground, which embeds and compares a few texts, and Search, which ranks the passages of a whole dataset against a query. Both call the same model and are billed like /embeddings calls.

Playground​

From Hosted models, choose Use model, then Open in Playground to open that project with the selected embedding model. Opening the Playground does not send an inference request; use Compare, Embed, or Search to run one.

The global Playground also offers Text and Embeddings tabs. Choose an embedding project in Parameters to use the same three modes with that project's models and billing scope. The selected task and project are kept in the URL.

The mode selector always shows Search, Similarity, and Vector. Search is disabled with an explanation if indexing is unavailable or the project has no available embedding model. Public bases work in all three modes without fine-tuning or creating a hosted alias. Similarity includes refunds and API-access examples. Choosing an example only fills the inputs; pressing Compare sends the metered inference request. Dimensions, normalization and query instructions follow the served model and are not per-request overrides. The Base model badge identifies a catalog model.

POST /api/v1/projects/{owner_slug}/{project_slug}/playground/embeddings/vector
POST /api/v1/projects/{owner_slug}/{project_slug}/playground/embeddings/similarity

Vector takes {model, input, input_type} and returns the vectors for your texts, with the exact model revision (target) that produced them and the effective instruction. input_type is query or document; a model trained with a query_instruction applies it to queries only.

Similarity takes {model, source, documents} and returns the cosine similarity of each document to the query, in input order. It embeds the query and then the documents, in batches, and each is billed as an embedding request: usage.billable_requests says how many. If a later request fails, the earlier ones may still be charged. Vector is billed the same way.

The same input limits as /embeddings apply, and they are enforced on the server.

Select a dataset by name in Corpus. Search ranks its indexed snapshot against a query. Snapshot IDs are available under Snapshot details, rather than in the main selector.

GET    /api/v1/projects/{owner_slug}/{project_slug}/search/corpora
GET    /api/v1/projects/{owner_slug}/{project_slug}/search/versions
GET    /api/v1/projects/{owner_slug}/{project_slug}/search/indexes
POST   /api/v1/projects/{owner_slug}/{project_slug}/search/indexes
POST   /api/v1/projects/{owner_slug}/{project_slug}/search/indexes/{index_id}/query
POST   /api/v1/projects/{owner_slug}/{project_slug}/search/indexes/{index_id}/cancel
DELETE /api/v1/projects/{owner_slug}/{project_slug}/search/indexes/{index_id}

Build an index. GET /search/corpora lists active embedding datasets by name, with example counts and current selection digests. Send dataset_id, model and credit_ceiling to POST /search/indexes. This captures the complete current dataset, without requiring a training run or a train/evaluation split. The API also accepts dataset_version_id for an existing snapshot; send exactly one of these two identifiers. GET /search/versions exposes historical snapshots and Search limits. Building embeds every distinct positive and negative passage with the public base or hosted model you choose, in batches billed at that model's ordinary rate; each batch appears in your credit ledger. You set a credit ceiling for the build: it stops sending batches once the spend reaches the ceiling, and a batch already running may finish slightly past it. An index is ready when its status says so; its embedded_count and spent_credits show progress.

Dataset edits. Edits do not change the existing index or start a billed rebuild. The Playground shows Dataset changed when its current selection digest differs from the indexed snapshot. Choose Update index and approve a credit ceiling to capture and embed the new contents. The old index remains available until deleted and continues to count against the storage quota.

Only one index can build at a time in a project, including a queued build waiting for an endpoint. Switching model or Corpus does not free that slot. The Playground identifies a blocking build outside your current selection and offers Stop indexing; Build and Update remain disabled until that build stops or finishes. You can also stop a queued/running index from the index inventory under snapshot details, loading older indexes if needed. Ready indexes remain searchable.

Stop indexing. Queued, running and retrying builds have a Stop indexing action, also available as POST /search/indexes/{index_id}/cancel. It marks the index stopped and prevents automatic retries. A batch already started may finish computing, but its late response cannot commit new vectors or a charge after cancellation. Charges already committed remain visible, together with partial progress. Stopping does not release storage: delete the stopped index when you no longer need it. Repeating Stop is safe; ready or failed indexes answer 409 search_index_not_building because no build remains to stop.

Query it. Each query embeds your text once (one ordinary billed request) and ranks the index exactly by cosine similarity, returning each passage with its rank, score, the example it came from and whether it was truncated.

Limits. One index holds at most 20,000 passages, and a project's indexes share 256 MB of vector storage. Stored vectors have no separate charge.

Model identity. Use a public ID such as ReOpenly/Qwen3-Embedding-0.6B or a hosted alias in the same model field. A base index returns saved_model_id: null, base_model_artifact_id and its public model ID; a hosted index retains its integer saved_model_id. Both pin the exact artifact and serving policy and share ownership, billing, quotas and cancellation.

Stale indexes. If a public base changes or becomes unavailable, the hosted model is pointed at another model, disabled or changed, or the version is no longer available, the index is reported stale and refuses queries: delete it and build a new one. Deleting an index removes its passages and vectors at once; credits already spent are not refunded. A failed index keeps counting against the storage quota until you delete it.

If Search or the Playground is not available for your project, the API answers 409 project_capability_mismatch.

Every field of these requests and responses is in the API reference.

Saved requests​

Successful Search, Similarity and Vector requests save their inputs, model, settings and returned results in History. They remain available after you leave the page or reload. Open a saved request to restore its results without sending another inference request or adding another inference charge. Saved Search results remain a snapshot even if the corpus or index later changes.

Use the delete button beside a history entry to remove its saved inputs and results. This does not delete a Search index, dataset or model, or refund the original inference charge. History is private to your account and project, stays until you delete it or erase your account, and can be read or deleted when serving is unavailable. If saving fails, the result stays visible and Retry saves it without rerunning inference.

The shared session API accepts a typed embedding_run containing mode, model, mode-specific inputs and result (maximum 2 MB). These are client-recorded snapshots, not independently verified billing or quality records. List responses expose embedding_mode, but omit inputs and results; read one session to retrieve them.

Session history pagination​

GET /api/v1/playground/sessions always returns {data, next_cursor, total_count}. Use limit (default 25, maximum 100) and pass cursor=<next_cursor> for the next page. Lists omit message bodies and can be filtered by the owner/project pair. Use task=embedding or task=text_generation to separate the two histories; omitting task lists both. A cursor belongs to its original task and scope.