Skip to main content
  1. Sign up — Create an account at platform.respan.ai
  2. Create an API key — Generate one on the API keys page
  3. Add credits or a provider key — Add credits on the Credits page or connect your own provider key on the Integrations page
Add the Docs MCP to your AI coding tool to get help building with Respan. No API key needed.
{
  "mcpServers": {
    "respan-docs": {
      "url": "https://docs.respan.ai/mcp"
    }
  }
}

​
What is Marqo?

Marqo is an end-to-end vector search engine that handles embedding generation, storage, and retrieval. It supports text, images, and multimodal search out of the box. Respan auto-instruments Marqo operations so every add, search, and index operation is captured as a traced span.

​
Setup

1

Install packages

pip install respan-ai opentelemetry-instrumentation-marqo marqo python-dotenv
2

Set environment variables

export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
export MARQO_URL="http://localhost:8882"
3

Initialize and run

import os
from dotenv import load_dotenv

load_dotenv()

import marqo
from respan import Respan

# Initialize Respan with auto-instrumentation
respan = Respan(is_auto_instrument=True)

# Create a Marqo client
client = marqo.Client(url=os.getenv("MARQO_URL", "http://localhost:8882"))

# Create an index
client.create_index("respan-demo", model="hf/e5-base-v2")

# Add documents (Marqo auto-generates embeddings)
client.index("respan-demo").add_documents(
    [
        {"_id": "doc_1", "title": "Introduction to machine learning", "content": "ML is a subset of AI."},
        {"_id": "doc_2", "title": "Vector databases explained", "content": "Vector DBs enable similarity search."},
        {"_id": "doc_3", "title": "Building search engines", "content": "Search engines index and retrieve documents."},
    ],
    tensor_fields=["title", "content"],
)

# Search
results = client.index("respan-demo").search("How do vector databases work?")
print(results)

respan.flush()
4

View your trace

Open the Traces page to see your Marqo spans including index creation, add, and search operations.

​
Configuration

ParameterTypeDefaultDescription
api_keystr | NoneNoneFalls back to RESPAN_API_KEY env var.
base_urlstr | NoneNoneFalls back to RESPAN_BASE_URL env var.
is_auto_instrumentbool | NoneFalseAuto-discover installed instrumentors. Required for Traceloop instrumentors.
customer_identifierstr | NoneNoneDefault customer identifier for all spans.
metadatadict | NoneNoneDefault metadata attached to all spans.
environmentstr | NoneNoneEnvironment tag (e.g. "production").

​
Attributes

Attach customer identifiers, thread IDs, and metadata to spans.

​
In Respan()

Set defaults at initialization — these apply to all spans. 
from respan import Respan

respan = Respan(
    is_auto_instrument=True,
    customer_identifier="user_123",
    metadata={"service": "search-api", "version": "1.0.0"},
)

​
With propagate_attributes

Override per-request using a context manager. 
from respan import Respan, propagate_attributes

respan = Respan(is_auto_instrument=True)

with propagate_attributes(
    customer_identifier="user_456",
    thread_identifier="session_abc",
    metadata={"plan": "enterprise"},
):
    results = client.index("respan-demo").search("semantic search techniques")
    print(results)
AttributeTypeDescription
customer_identifierstrIdentifies the end user in Respan analytics.
thread_identifierstrGroups related messages into a conversation.
metadatadictCustom key-value pairs. Merged with default metadata.

​
Examples

​
Create index

import marqo

client = marqo.Client(url="http://localhost:8882")

# Create with a specific model
client.create_index("products", model="hf/e5-base-v2")

​
Add documents

client.index("products").add_documents(
    [
        {
            "_id": "product_001",
            "name": "Wireless Headphones",
            "category": "electronics",
            "description": "Noise-cancelling wireless headphones with 30-hour battery life.",
        },
        {
            "_id": "product_002",
            "name": "Cotton T-Shirt",
            "category": "clothing",
            "description": "Premium cotton t-shirt available in multiple colors.",
        },
        {
            "_id": "product_003",
            "name": "Running Shoes",
            "category": "footwear",
            "description": "Lightweight running shoes with responsive cushioning.",
        },
    ],
    tensor_fields=["name", "description"],
)

# Basic text search
results = client.index("products").search("comfortable audio equipment")

for hit in results["hits"]:
    print(f"{hit['name']}: score={hit['_score']:.4f}, category={hit['category']}")

# Filtered search
results = client.index("products").search(
    "comfortable audio equipment",
    filter_string="category:electronics",
)

# Search with specific searchable attributes
results = client.index("products").search(
    "comfortable audio equipment",
    searchable_attributes=["description"],
)

​
Delete

# Delete by IDs
client.index("products").delete_documents(ids=["product_001", "product_002"])