Compositions

Combine results from multiple indices, content types, and data sources into a single response.

The Composition API lets you combine results from multiple indices, content types and data sources into a single response. Use it to build federated search, category pages, and dynamic experiences where curated or sponsored content needs to appear alongside . Manage compositions in the Algolia dashboard and render them with InstantSearch. Update experiences without changing frontend code.

What you can do with compositions

• Compose results from multiple sources: combine multiple indices, content types and data sources in a single request; no frontend orchestration needed.
• Inject Smart Groups: place curated product groups at specific positions within organic results. Inject sponsored content, trending items, brand partnerships and more.
• Scalable orchestration: complex orchestration logic lives within the composition. Frontend teams can focus on creating the best possible rendering and experience for their customers.

When to use compositions

Use the Composition API when you need to return multiple result sets in one request, inject dynamic sponsored results at specific locations, build collections and category pages or federated search experiences.

Key concepts

Composition

A composition combines results from multiple sources into one response, so your frontend can query a single endpoint instead of searching each source separately.

Composition rule

Defines when and where groups are injected, triggered by a query, catalog, or collection.

Smart Group

A defined set of results matching specific attribute criteria, injected at a chosen position within an organic results feed.

Category page

A product landing page built from a search request with applied filters.

Collection

Curated product listings. You can create a collection by manually selecting records or defining them using conditions.

Search-based groups

Search-based groups use Algolia filters to automatically select items that match your criteria. You define what to promote (like brand:Adidas AND in_stock:true), and Algolia finds which items match.

Algolia’s AI-powered ranking determines which matching items are most relevant to the user’s query, ensuring promoted items still feel natural in the context of their search.

External source groups

External source groups let you specify which items to promote by providing a list of object IDs. These object IDs come from an external system like:

• Retail media platforms
• Custom bidding or campaign management systems

Your backend calls the external source, receives objectIDs, then passes them to Algolia’s Composition API. Algolia handles injection, deduplication, and optional re-ranking by relevance.

Recommend-based groups

Recommend-based groups let you populate a group with items returned by an Algolia Recommend model. You configure them through the Composition API by setting the group source to recommend.

Before you begin using the Compositions API

Before using the Composition API, make sure your setup meets these requirements:

• Your Algolia application must use Algolia’s dynamic scaling infrastructure. If your application uses classic infrastructure, it must be migrated (contact your Algolia customer success manager or the support team).
• You must have access to Merchandising Studio to curate results.
• Your application must have the Composition API and Smart Groups enabled. If you think your plan includes these features but you can’t access them, contact your Algolia account manager, customer success manager, or the support team.
• Multifeed compositions require additional access. To request it, contact your Algolia customer success manager.