Configure cross-project search

With cross-project search (CPS), users in your organization can search across multiple Elastic Cloud Serverless projects at once, instead of searching each project individually. When your data is split across projects to organize ownership, use cases, or environments, cross-project search lets you query all the data from a single place.

This section explains how to set up and manage cross-project search for your organization, including linking projects, managing user access, and refining scope.

• Link and manage projects: link projects in the Elastic Cloud UI, manage linked projects, and unlink projects.
• Access and scope: manage user access across linked projects and configure the default cross-project search scope per space.
• Impacts and limitations: understand how cross-project search affects alerting, dashboards, and other features, and review current limitations.

For end-user search workflows, syntax, and examples, refer to Cross-project search in Explore and analyze.

Cross-project search runs across origin and linked projects within your Elastic Cloud organization:

• Origin project: The base project where you create links and run cross-project searches.
• Linked projects: The projects you connect to the origin project. Data in the linked projects becomes searchable from the origin project.

After you link projects, searches from the origin project run across the origin and all linked projects by default. Searches are designed to run across projects automatically, providing the same experience for querying, analysis, and insights across projects as within a single project. Restricting search scope is always possible, but it requires explicitly scoping the search request using qualified expressions, the _origin identifier, or routing parameters.

To adjust the default scope, you can configure the default CPS scope for each space.

For details about project IDs and aliases (used in search expressions), refer to Project ID and aliases.

To configure cross-project search, make sure you meet these prerequisites:

• You must be an organization owner or project administrator.
• Your origin and linked projects must be compatible.
• For programmatic access, you must use Elastic Cloud API keys, not project-scoped API keys. Elastic Cloud API keys can authenticate across project boundaries. Project-scoped API keys (such as Elasticsearch API keys) can't search across project boundaries, so they return origin-only results.

You can link any combination of Elasticsearch, Elastic Observability, and Elastic Security projects, with the following requirements and limitations:

• Elasticsearch projects require the Serverless Plus add-on.
• Elastic Security Serverless and Elastic Observability Serverless projects require the Complete feature tier. Projects on the Essentials tier are not compatible with cross-project search.
• Workplace AI projects are not compatible with cross-project search.

Only compatible projects appear in the cross-project search linking wizard.

When configuring cross-project search, consider how the CPS architecture (or linking pattern) will affect searches, dashboards, and alerting across your organization. Cross-project search supports three patterns, each with a different level of operational risk.

For most deployments, we recommend creating a dedicated overview project that can act as an origin project. You can also think of this as a hub-and-spoke model.

In this architecture, you create a new, empty project and link existing projects to it. You run all cross-project searches and dashboards from the new overview project, while your actual active projects continue to operate independently. The linked ("spoke") projects are not linked to each other.

TODO add diagram

The overview project becomes a central point for broad searches, dashboards, and investigations, without affecting your existing setup (for example, isolated projects stay isolated).

The overview project model is strongly recommended and appropriate for most CPS configurations. These additional patterns are valid, but they involve additional risk and require careful configuration:

• Shared data project (N-to-1): A single project stores data from a shared service (for example, logs). Multiple origin projects link to this central data project.

  The N-to-1 pattern is often used when several teams need to query shared data independently. The main risk is that linking to a shared data project affects searches, dashboards, and alerts in each origin project. If the shared project is a large, active project, the expanded dataset might cause unexpected behavior. If you're using this pattern, make sure to manage user access and consider CPS scope.

• Data mesh (N-to-N): Multiple active projects link directly to each other.

  The N-to-N pattern is the most complex and involves the highest risk. After you link projects, all searches, dashboards, and alerting rules in each origin project will query data from every linked project by default, which might make workflows unpredictable. Make sure you check alerting rules, which might be applied to data that the rule was never intended to evaluate.

You can also link and unlink projects using the Elastic Cloud API. In the linking wizard, click View API request on the review step to see the equivalent API call for your current selection.

For information about searching across linked projects using APIs, refer to Cross-project search.