---
title: Using project routing to limit search scope
description: Learn how to use project routing to limit cross-project search (CPS) queries to specific projects based on tag values.
url: https://www.elastic.co/elastic/docs-builder/docs/3016/explore-analyze/cross-project-search/cross-project-search-project-routing
products:
  - Elasticsearch
applies_to:
  - Elastic Cloud Serverless: Preview
  - Elastic Stack: Unavailable
---

# Using project routing to limit search scope
Project routing enables you to limit a search to a subset of projects, including the origin project and linked projects, based on tag values.
When you use project routing, the routing decision is made before the search request is performed.
Based on the specified tags, CPS determines which projects the query is sent to, and the search is performed only on those projects.
For an overview of cross-project search concepts, refer to [Cross-project search](https://www.elastic.co/elastic/docs-builder/docs/3016/explore-analyze/cross-project-search). For details on available tags, refer to [Tags in CPS](https://www.elastic.co/elastic/docs-builder/docs/3016/explore-analyze/cross-project-search/cross-project-search-tags).
The `project_routing` parameter is available on all CPS-enabled endpoints. Refer to the [supported APIs](/elastic/docs-builder/docs/3016/explore-analyze/cross-project-search#cps-supported-apis) for a full list of endpoints.
For example, the following API request searches the `logs` resource only on projects that have the `_alias:my_search_project` tag.
```json

{
  "project_routing": "_alias:my_search_project"
}
```

<important>
  Currently, project routing only supports using the `_alias` tag.
</important>

Refer to [the examples section](/elastic/docs-builder/docs/3016/explore-analyze/cross-project-search#cps-examples) for more.

## Using named project routing expressions

You can define named project routing expressions and reference them in the `project_routing` parameter of any cross-project search-enabled endpoint that supports project routing.
Named expressions enable you to assign a reusable name to a routing expression. This makes complex routing rules easier to reference and reuse across multiple requests.
To reference a named project routing expression in a `project_routing` parameter, prefix its name with the `@` character.
For example, the following [`_search` API](https://www.elastic.co/docs/api/doc/elasticsearch/v9/operation/operation-search) request and [ES|QL query](https://www.elastic.co/docs/api/doc/elasticsearch/v9/operation/operation-esql-query) search the `logs` resource only on projects that match the `@custom-expression` routing rule.
<tab-set>
  <tab-item title="API request">
    ```json

    {
    "project_routing": "@custom-expression",
    "query": { ... }
    }
    ```
  </tab-item>

  <tab-item title="ES|QL">
    ```json
    SET project_routing="@custom-expression";
    FROM logs 
    | STATS COUNT(*)
    ```
  </tab-item>
</tab-set>


### Creating and managing named project routing expressions

You can use the `_project_routing` API to create and manage named project routing expressions.
<note>
  Named project routing expressions are project-specific. An expression can be used only in the project where it was created.
</note>

The following request creates a named expression called `origin-only`:
```json

{
    "expression" : "_alias:origin"
}
```

You can also create multiple named expressions in a single request:
```json

{
"origin-only": { "expression": "_alias:origin" },
"linked-security": { "expression": "_alias:*sec*" }
}
```

The GET `_project_routing` endpoint retrieves information about named expressions.
To retrieve all named expressions:
```json
```

To retrieve a specific named expression:
```json
```

To delete a named expression:
```json
```

<note>
  When using the `_project_routing` API to create, retrieve, or delete expressions, do not prefix the expression name with `@`. The `@` prefix is required only when referencing a named expression in the `project_routing` parameter of API endpoints that support it.
</note>