# List Stores URL: https://www.mixedbread.com/api-reference/endpoints/stores/manage/list-stores List all stores with optional search. ```json { "paths": { "/v1/stores": { "get": { "tags": [ "stores" ], "summary": "List Stores", "operationId": "list_stores", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Maximum number of items to return per page (1-100)", "examples": [ 10, 20, 50 ], "default": 20, "title": "Limit" }, "description": "Maximum number of items to return per page (1-100)" }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for forward pagination - get items after this position. Use last_cursor from previous response.", "examples": [ "eyJjcmVhdGVkX2F0IjoiMjAyNC0xMi0zMVQyMzo1OTo1OS4wMDBaIiwiaWQiOiJhYmMxMjMifQ==" ], "title": "After" }, "description": "Cursor for forward pagination - get items after this position. Use last_cursor from previous response." }, { "name": "before", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for backward pagination - get items before this position. Use first_cursor from previous response.", "examples": [ "eyJjcmVhdGVkX2F0IjoiMjAyNC0xMi0zMVQyMzo1OTo1OS4wMDBaIiwiaWQiOiJhYmMxMjMifQ==" ], "title": "Before" }, "description": "Cursor for backward pagination - get items before this position. Use first_cursor from previous response." }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Whether to include total count in response (expensive operation)", "examples": [ false, true ], "default": false, "title": "Include Total" }, "description": "Whether to include total count in response (expensive operation)" }, { "name": "q", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Search query for fuzzy matching over name and description fields", "title": "Q" }, "description": "Search query for fuzzy matching over name and description fields" }, { "name": "tags", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" }, "maxItems": 32 }, { "type": "null" } ], "description": "Only return stores that carry every one of these tags", "title": "Tags" }, "description": "Only return stores that carry every one of these tags" } ], "responses": { "200": { "description": "The list of stores", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreListResponse" }, "example": { "object": "list", "data": [ { "id": "vs_abc123", "object": "store", "name": "product-documentation", "description": "Product documentation and FAQs", "is_public": false, "metadata": {}, "tags": [], "config": { "contextualization": { "with_metadata": false, "with_file_context": false } }, "file_counts": { "in_progress": 0, "completed": 10, "failed": 0, "cancelled": 0, "pending": 0, "total": 10 }, "status": "completed", "usage_bytes": 2097152, "usage_tokens": 102400, "expires_after": null, "expires_at": null, "created_at": "2025-01-10T09:00:00.000Z", "updated_at": "2025-01-15T11:30:00.000Z", "last_active_at": "2025-01-15T14:00:00.000Z" }, { "id": "vs_def456", "object": "store", "name": "api-documentation", "description": "API reference documentation", "is_public": true, "metadata": {}, "tags": [], "config": { "contextualization": { "with_metadata": false, "with_file_context": false } }, "file_counts": { "in_progress": 0, "completed": 5, "failed": 0, "cancelled": 0, "pending": 0, "total": 5 }, "status": "completed", "usage_bytes": 1048576, "usage_tokens": 51200, "expires_after": null, "expires_at": null, "created_at": "2025-01-12T10:15:00.000Z", "updated_at": "2025-01-14T09:20:00.000Z", "last_active_at": "2025-01-15T13:45:00.000Z" } ], "pagination": { "has_more": false, "first_cursor": "eyJpZCI6InZzX2FiYzEyMyJ9", "last_cursor": "eyJpZCI6InZzX2RlZjQ1NiJ9" } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "StoreListResponse": { "properties": { "pagination": { "$ref": "#/components/schemas/CursorPaginationResponse" }, "object": { "type": "string", "const": "list", "title": "Object", "description": "The object type of the response", "default": "list" }, "data": { "items": { "$ref": "#/components/schemas/Store" }, "type": "array", "title": "Data", "description": "The list of stores" } }, "type": "object", "required": [ "pagination", "data" ], "title": "StoreListResponse" }, "CursorPaginationResponse": { "properties": { "has_more": { "type": "boolean", "title": "Has More", "description": "Contextual direction-aware flag: True if more items exist in the requested pagination direction. For 'after': more items after this page. For 'before': more items before this page.", "examples": [ true, false ] }, "first_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Cursor", "description": "Cursor of the first item in this page. Use for backward pagination. None if page is empty.", "examples": [ "eyJjcmVhdGVkX2F0IjoiMjAyNC0xMi0zMVQyMzo1OTo1OS4wMDBaIiwiaWQiOiJhYmMxMjMifQ==", null ] }, "last_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Cursor", "description": "Cursor of the last item in this page. Use for forward pagination. None if page is empty.", "examples": [ "eyJjcmVhdGVkX2F0IjoiMjAyNC0xMi0zMFQyMzo1OTo1OS4wMDBaIiwiaWQiOiJ4eXo3ODkifQ==", null ] }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total", "description": "Total number of items available across all pages. Only included when include_total=true was requested. Expensive operation - use sparingly.", "examples": [ 42, 0, null ] } }, "type": "object", "required": [ "has_more", "first_cursor", "last_cursor" ], "title": "CursorPaginationResponse", "description": "Response model for cursor-based pagination." }, "Store": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier for the store", "examples": [ "1b8b486e-16d0-400b-8868-04cd75217a7e" ] }, "name": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Name", "description": "Name of the store", "examples": [ "customer-support-kb", "product-documentation" ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "null" } ], "title": "Description", "description": "Detailed description of the store's purpose and contents", "examples": [ "Contains customer support articles and FAQs" ] }, "is_public": { "type": "boolean", "title": "Is Public", "description": "Whether the store can be accessed by anyone with valid login credentials", "default": false, "examples": [ false ] }, "license": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License", "description": "License for public stores" }, "metadata": { "anyOf": [ {}, { "type": "null" } ], "title": "Metadata", "description": "Additional metadata associated with the store", "examples": [ { "category": "support", "language": "en" } ] }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags", "description": "Tags for organizing stores", "examples": [ [ "production", "docs" ] ] }, "config": { "anyOf": [ { "$ref": "#/components/schemas/StoreConfig" }, { "type": "null" } ], "description": "Store-level configuration defaults" }, "bucket_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Bucket Id", "description": "Customer bucket backing this store's storage; null = platform default" }, "file_counts": { "$ref": "#/components/schemas/FileCounts", "description": "Counts of files in different states" }, "expires_after": { "anyOf": [ { "$ref": "#/components/schemas/ExpiresAfter" }, { "type": "null" } ], "description": "Optional expiration policy" }, "status": { "$ref": "#/components/schemas/StoreStatus", "description": "Processing status of the store", "default": "completed" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when the store was created", "examples": [ "2024-01-01T00:00:00Z" ] }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Timestamp when the store was last updated", "examples": [ "2024-01-01T00:00:00Z" ] }, "last_active_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Active At", "description": "Timestamp when the store was last used" }, "usage_bytes": { "type": "integer", "title": "Usage Bytes", "description": "Total storage usage in bytes", "default": 0, "examples": [ 1024000 ] }, "usage_tokens": { "type": "integer", "title": "Usage Tokens", "description": "Total storage usage in tokens", "default": 0, "examples": [ 1024000 ] }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At", "description": "Optional expiration timestamp for the store", "examples": [ "2024-01-01T00:00:00Z" ] }, "copy_state": { "anyOf": [ { "$ref": "#/components/schemas/StoreCopyInfo" }, { "type": "null" } ], "description": "Set while the store is being copied from or into, and when a copy into it failed" }, "object": { "type": "string", "const": "store", "title": "Object", "description": "Type of the object", "default": "store" } }, "type": "object", "required": [ "id", "name", "created_at", "updated_at" ], "title": "Store", "description": "Model representing a store with its metadata and timestamps." }, "StoreConfig": { "properties": { "contextualization": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/ContextualizationConfig" } ], "title": "Contextualization", "description": "Include additional context when embedding chunks.", "default": false }, "lsf": { "anyOf": [ { "$ref": "#/components/schemas/LsfStoreConfig" }, { "type": "null" } ], "description": "Learn a scoring function for this store. Searches are captured as training data, a model is trained from reranking and answer signals, and once trained, searches apply it by default (override per search with the lsf option). Pass an empty object to enable it." } }, "type": "object", "title": "StoreConfig", "description": "Configuration for a store." }, "ContextualizationConfig": { "properties": { "with_metadata": { "anyOf": [ { "type": "boolean" }, { "items": { "type": "string" }, "type": "array" } ], "title": "With Metadata", "description": "Include all metadata or specific fields in the contextualization. Supports dot notation for nested fields (e.g., 'author.name'). When True, all metadata is included (flattened). When a list, only specified fields are included.", "default": false, "examples": [ true, false, [ "title", "author.name", "author.email", "tags" ] ] }, "with_file_context": { "type": "boolean", "title": "With File Context", "description": "Use an LLM to generate a short context for each chunk that situates it within the full document, improving retrieval accuracy.", "default": false } }, "type": "object", "title": "ContextualizationConfig" }, "LsfStoreConfig": { "properties": {}, "type": "object", "title": "LsfStoreConfig", "description": "Learned-scoring-function settings a store opts into; an empty object enables it." }, "FileCounts": { "properties": { "pending": { "type": "integer", "title": "Pending", "description": "Number of files waiting to be processed", "default": 0, "examples": [ 5 ] }, "in_progress": { "type": "integer", "title": "In Progress", "description": "Number of files currently being processed", "default": 0, "examples": [ 5 ] }, "cancelled": { "type": "integer", "title": "Cancelled", "description": "Number of files whose processing was cancelled", "default": 0, "examples": [ 2 ] }, "completed": { "type": "integer", "title": "Completed", "description": "Number of successfully processed files", "default": 0, "examples": [ 42 ] }, "failed": { "type": "integer", "title": "Failed", "description": "Number of files that failed processing", "default": 0, "examples": [ 1 ] }, "total": { "type": "integer", "title": "Total", "description": "Total number of files", "default": 0, "examples": [ 50 ] } }, "type": "object", "title": "FileCounts", "description": "Tracks counts of files in different states within a store." }, "ExpiresAfter": { "properties": { "anchor": { "type": "string", "const": "last_active_at", "title": "Anchor", "description": "Anchor date for the expiration policy", "default": "last_active_at" }, "days": { "type": "integer", "title": "Days", "description": "Number of days after which the store expires", "default": 30 } }, "type": "object", "title": "ExpiresAfter", "description": "Represents an expiration policy for a store." }, "StoreStatus": { "type": "string", "enum": [ "expired", "in_progress", "completed", "failed" ], "title": "StoreStatus", "description": "Status of a store." }, "StoreCopyInfo": { "properties": { "role": { "type": "string", "enum": [ "source", "target" ], "title": "Role", "description": "Whether this store is copied from or into" }, "status": { "type": "string", "enum": [ "in_progress", "failed" ], "title": "Status", "description": "Progress of the copy" }, "peer_store_id": { "type": "string", "title": "Peer Store Id", "description": "The other store of the copy" }, "started_at": { "type": "string", "format": "date-time", "title": "Started At", "description": "When the copy was requested" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Why the copy failed, when it did" } }, "type": "object", "required": [ "role", "status", "peer_store_id", "started_at" ], "title": "StoreCopyInfo", "description": "Progress of a store copy, present on both the source and the target while it runs." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } ``` Python: ```python from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") response = mxbai.stores.list(limit=20) for store in response.data: print(store) ``` Python (async): ```python from mixedbread import AsyncMixedbread mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") response = await mxbai.stores.list(limit=20) for store in response.data: print(store) ``` TypeScript: ```ts import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: "YOUR_API_KEY", }); const response = await mxbai.stores.list({ limit: 20, }); for (const store of response.data) { console.log(store); } ``` cURL: ```bash curl 'https://api.mixedbread.com/v1/stores?limit=20' \ -H 'Authorization: Bearer YOUR_API_KEY' ```