Managing routes

Creating a route using the UI

Complete the following steps to create a route using the UI.

1. Log in to your IBM Cloud account.

2. Click the Menu icon > Observability.

3. Click Logging > Routing.

4. In the Routes tab, click Create.

5. In Routing rules section, modify the Action for Rule 1:

   Select an Action for Rule 1:

   • Select Send logs from for the rule to route platform logs to the associated targets.

   • Select Drop logs from for the rule to drop platform logs matching this rule.

   Add the inclusion filters to determine the platform logs routed to the targets specified in the rule.

   • Select a condition, and specify the location values to be matched by the inclusion filter.

   • To add multiple inclusion filters, click Add filter to add additional filters.

   Add the targets to associate with the rule by selecting a target from the list. If you do not have a target defined, click Add target to create a new one.

6. Click Add rule to add additional rules to the route.

   The order of route rules affects the routing behavior. Rules are processed in order and once a rule is matched, the subsequent rules are not processed.

   The order of the routing rules can be changed by clicking the up and down arrows to the right of each rule definition.

   If you need to remove a rule or filter, click the Remove icon associated with the rule or filter.

   You can configure up to 10 rules per route.

7. Click Next.

8. Enter a name for the route.

9. Review the route definition ensuring the order of the rules is as intended.

   For more information, see Understanding routing precedence.

10. Click Create.

Updating a route using the UI

Complete the following steps to update a route using the UI.

1. Log in to your IBM Cloud account.

2. Click the Menu icon > Observability.

3. Click Logging > Routing.

4. In the Routes tab, determine which route to update and click the .

5. Click Rename to rename the route.

6. Click Edit to update the route rules.

   In Routing rules, modify the Action for the rule:

   • Select Send for the rule to route platform logs to the associated targets.

   • Select Drop for the rule to drop platform logs matching this rule.

   Add or modify the inclusion filters to determine the platform logs routed to the targets specified in the rule.

   Select the desired filter and condition and specify the value to be matched by the inclusion filter.

   To add multiple inclusion filters, click Add filter to add additional filters.

7. Modify the target to associate with the rule by selecting a target from the list. If you do not have a target defined, click Add target to create a new target.

8. Click Add rule to add additional rules to the route.

   The order of route rules affects the routing behavior. Rules are processed in order and once a rule is matched, the subsequent rules are not processed.

   The order of the routing rules can be changed by clicking the up and down arrows to the right of each rule definition.

   If you need to remove a rule or filter, click the Remove icon associated with the rule or filter.

   You can configure up to 10 rules per route.

9. Click Update to make changes to your route.

Viewing a route using the UI

Complete the following steps to view a route using the UI.

1. Log in to your IBM Cloud account.

2. Click the Menu icon > Observability.

3. Click Logging > Routing.

4. In the Routes tab, you can see the list of configured routes.

   The order of the routes does not affect the routing behavior since they are processed independently.

   Each route displays the route name and rules.

   The routes page also displays Routing guidance with additional information about configuring routing.

Deleting a route using the UI

Complete the following steps to delete a route using the UI.

1. Log in to your IBM Cloud account.

2. Click the Menu icon > Observability.

3. Click Logging > Routing.

4. In the Routes tab, determine which route to delete and click the .

5. Click Delete to delete the entire route. You must enter the route name before the route is deleted.

CLI prerequisites

Before you use the CLI to manage routes, complete the following steps:

1. Install the IBM Cloud CLI.

2. Install the IBM Cloud Logs Routing CLI.

3. Log in to IBM Cloud. Run the following command: ibmcloud login

Creating a route by using the CLI

Use this command to create a route.

Route names are unique in the account.

ibmcloud logs-router route create --name NAME --rules RULES | @RULES-FILE [--output FORMAT] [--force]

ibmcloud logs-router route create --name route3 --rules '[{"action": "send", "targets":[{"id":"0b4e6aa9-257c-4a3a-ae42-9a36a5b3adc7"},{"id":"6f9137b3-2bb9-4724-851b-153e23c82d80"}],"inclusion_filters": [{"operand": "location", "operator": "in", "values": ["us-south","eu-de"]}]}]'

Id           cfa2be32-979d-4e99-a2a2-e68e65e9b8cc
Name         route3
Rules
             action              send
             inclusion_filters
                                 operand    location
                                 operator   in
                                 values     [us-south, eu-de]

             targets
                                 id            0b4e6aa9-257c-4a3a-ae42-9a36a5b3adc7
                                 name          cl-target2
                                 target_type   cloud-logs

                                 id            6f9137b3-2bb9-4724-851b-153e23c82d80
                                 name          cl-platform-logs-sydney-113
                                 target_type   cloud-logs


Created At   2026-04-29T12:59:25.764Z
Updated At   2026-04-29T12:59:25.764Z
Managed By   account

ibmcloud logs-router route create --name route4 --rules '[{"action": "send", "targets":[{"id":"0b4e6aa9-257c-4a3a-ae42-9a36a5b3adc7"},{"id":"6f9137b3-2bb9-4724-851b-153e23c82d80"}],"inclusion_filters": [{"operand": "location", "operator": "in", "values": ["us-south","eu-de"]}]},{"action": "send", "targets":[{"id":"0b4e6aa9-257c-4a3a-ae42-9a36a5b3adc7"},{"id":"6f9137b3-2bb9-4724-851b-153e23c82d80"}],"inclusion_filters": [{"operand": "location", "operator": "is", "values": ["us-east"]}]}]'

Id           6bb85c44-7187-4e45-b850-c912ddd2d0bf
Name         route4
Rules
             action              send
             inclusion_filters
                                 operand    location
                                 operator   in
                                 values     [us-south, eu-de]

             targets
                                 id            0b4e6aa9-257c-4a3a-ae42-9a36a5b3adc7
                                 name          cl-target2
                                 target_type   cloud-logs

                                 id            6f9137b3-2bb9-4724-851b-153e23c82d80
                                 name          cl-platform-logs-sydney-113
                                 target_type   cloud-logs


             action              send
             inclusion_filters
                                 operand    location
                                 operator   is
                                 values     [us-east]

             targets
                                 id            0b4e6aa9-257c-4a3a-ae42-9a36a5b3adc7
                                 name          cl-target2
                                 target_type   cloud-logs

                                 id            6f9137b3-2bb9-4724-851b-153e23c82d80
                                 name          cl-platform-logs-sydney-113
                                 target_type   cloud-logs


Created At   2026-04-29T13:01:11.685Z
Updated At   2026-04-29T13:01:11.685Z
Managed By   account

Updating a route using the CLI

Use this command to update a route. Any specified value that is different from when the route was originally created will be updated to the value specified in the command.

ibmcloud logs-router route update --id ROUTE [--name NAME] [--rules RULES | @RULES-FILE] [--output FORMAT] [--force]

Id           6bb85c44-7187-4e45-b850-c912ddd2d0bf
Name         my-new-route-name
Rules
             action              send
             inclusion_filters
                                 operand    location
                                 operator   in
                                 values     [us-south, eu-de]

             targets
                                 id            0b4e6aa9-257c-4a3a-ae42-9a36a5b3adc7
                                 name          cl-target2
                                 target_type   cloud-logs

                                 id            6f9137b3-2bb9-4724-851b-153e23c82d80
                                 name          cl-platform-logs-sydney-113
                                 target_type   cloud-logs


             action              send
             inclusion_filters
                                 operand    location
                                 operator   is
                                 values     [us-east]

             targets
                                 id            0b4e6aa9-257c-4a3a-ae42-9a36a5b3adc7
                                 name          cl-target2
                                 target_type   cloud-logs

                                 id            6f9137b3-2bb9-4724-851b-153e23c82d80
                                 name          cl-platform-logs-sydney-113
                                 target_type   cloud-logs


Created At   2026-04-29T13:01:11.685Z
Updated At   2026-04-29T13:07:32.677Z
Managed By   account

Deleting a route using the CLI

Use this command to delete a route.

ibmcloud logs-router route delete --id route [--force]

Are you sure you want to delete? [y/n]> y
OK

Getting information about a route using the CLI

Use this command to get information about a route for an IBM Cloud Logs Routing region.

ibmcloud logs-router route get --id route [--output FORMAT]

Id           2a4739ee-7cd6-4e05-b60d-9b2e7b0b7981
Name         route2
Rules
             action    send
             targets
                       id            0b4e6aa9-257c-4a3a-ae42-9a36a5b3adc7
                       name          cl-target2
                       target_type   cloud-logs

                       id            6f9137b3-2bb9-4724-851b-153e23c82d80
                       name          cl-platform-logs-sydney-113
                       target_type   cloud-logs


Created At   2026-04-29T12:55:23.106Z
Updated At   2026-04-29T12:55:23.106Z
Managed By   account

Listing all routes in a region

Use this command to list the configured routes for an IBM Cloud Logs Routing region.

ibmcloud logs-router route list [--output FORMAT]

API routes and actions

The following table lists the actions that you can run to manage routes:

You can use private and public endpoints to manage routes. For more information about the list of ENDPOINTS that are available, see Endpoints.

• You can manage routes from the private network using an API endpoint with the following format: https://api.private.REGION.logs-router.cloud.ibm.com
• You can manage routes from the public network using an API endpoint with the following format: https://api.REGION.logs-router.cloud.ibm.com

You can disable the public endpoints by updating the account settings. For more information, see Configuring route and region settings.

For more information about the REST API, see routes.

API prerequisites

To make API calls to manage routes, complete the following steps:

1. Get an IAM access token. For more information, see Retrieving IAM access tokens.
2. Identify the API endpoint in the region where you plan to configure or manage a route. For more information, see Endpoints.

Creating a route using the API

You can use the following cURL command to create a route:

Route names are unique in the account. You cannot reuse a route name to configure multiple destinations.

curl -X POST <ENDPOINT>/v3/routes -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json" -d '{
    "name": "ROUTE_NAME",
    "rules": [
      {
        "action": "send",
        "targets": [
          {
            "id": "50375218-7cff-4234-bbb4-171bebab8408"
          },
          {
            "id": "c7519d8a-5f97-498b-a229-8542f60955cd"
          }
        ],
        "inclusion_filters": [
          {
            "operand": "location",
            "operator": "is",
            "values": ["us-east"]
          }
        ]
      }
    ]
  }'

Where

<ENDPOINT>

API endpoint in the region where you plan to configure or manage a route. For more information, see Endpoints.

ROUTE_NAME

The name to be given to the route.

The name to be given to the route.

The maximum length is 1000 characters.

The minimum length is 1 character.

The name cannot include any special characters other than empty space, -, ., _, :.

Do not include any personal identifying information (PII) in any resource names.

RULES

JSON string or a path to a JSON file prefix with @ that define how platform logs are routed.

Rules are evaluated in the order in which they are configured.

The maximum length is 10 rules.

For more information, see Defining routing rules.

For example, you can use the following cURL request to create a route:

curl -X POST https://api.us-south.logs-router.cloud.ibm.com/v3/routes -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json" -d '{
    "name": "My-route",
    "rules": [
      {
        "action": "send",
        "targets": [
          {
            "id": "0b4e6aa9-257c-4a3a-ae42-9a36a5b3adc7"
          },
          {
            "id": "6f9137b3-2bb9-4724-851b-153e23c82d80"
          }
        ],
        "inclusion_filters": [
          {
            "operand": "location",
            "operator": "is",
            "values": ["us-east"]
          },
          {
            "operand": "service_name",
            "operator": "in",
            "values": ["codeengine","container-registry"]
          }
        ]
      }
    ]
  }'

The output looks as follows:

{"id":"c7673f63-1260-4f86-bc1a-aaedb89391d8","name":"route5","crn":"crn:v1:bluemix:public:logs-router:global:a/xxxxxxx::route:c7673f63-1260-4f86-bc1a-aaedb89391d8","rules":[{"action":"send","targets":[{"id":"0b4e6aa9-257c-4a3a-ae42-9a36a5b3adc7","name":"cl-target2","crn":"crn:v1:bluemix:public:logs-router:eu-gb:a/xxxxxxx::target:0b4e6aa9-257c-4a3a-ae42-9a36a5b3adc7","target_type":"cloud-logs"},{"id":"6f9137b3-2bb9-4724-851b-153e23c82d80","name":"cl-platform-logs-sydney-113","crn":"crn:v1:bluemix:public:logs-router:eu-gb:a/xxxxxxx::target:6f9137b3-2bb9-4724-851b-153e23c82d80","target_type":"cloud-logs"}],"inclusion_filters":[{"operand":"location","operator":"is","values":["us-east"]}]}],"managed_by":"account","created_at":"2026-04-29T13:26:34.237Z","updated_at":"2026-04-29T13:26:34.237Z"}

Updating a route using the API

You can modify the name of a route and rules. Any specified value that is different from when the route was originally created will be updated to the value specified in the request.

When you update a route, you must include the route information in the data section of the request.

• You must pass all fields.
• Update the fields that need to be changed.

Route names are unique in the account. You cannot reuse a route name to configure multiple destinations.

You can use the following cURL command to update a route:

curl -X PATCH <ENDPOINT>/v3/routes/ROUTE_ID -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json" -d '{
    "name": "ROUTE_NAME",
    "rules": [
      {
        "action": "send",
        "targets": [
          {
            "id": "d3ebcda8-953d-45ea-a4a7-b47f8c4a9742"
          }
        ],
        "inclusion_filters": [
          {
            "operand": "location",
            "operator": "is",
            "values": ["eu-de"]
          }
        ]
      }
    ]
  }'

Where

<ENDPOINT>

API endpoint in the region where you plan to configure or manage a route. For more information, see Endpoints.

ROUTE_ID

ID of the route.

ROUTE_NAME

The name to be given to the route.

The name to be given to the route.

The maximum length is 1000 characters.

The minimum length is 1 character.

The name cannot include any special characters other than empty space, -, ., _, :.

Do not include any personal identifying information (PII) in any resource names.

RULES

JSON string or a path to a JSON file prefix with @ that define how platform logs are routed.

Rules are evaluated in the order in which they are configured.

The maximum length is 10 rules.

For more information, see Defining routing rules.

For example, you can use the following cURL request to create a route in Dallas:

curl -X PATCH https://api.us-south.logs-router.cloud.ibm.com/v3/routes/c7673f63-1260-4f86-bc1a-aaedb89391d8 -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json" -d '{
    "name": "My new route name",
    "rules": [
      {
        "action": "send",
        "targets": [
          {
            "id": "0b4e6aa9-257c-4a3a-ae42-9a36a5b3adc7"
          },
          {
            "id": "6f9137b3-2bb9-4724-851b-153e23c82d80"
          }
        ],
        "inclusion_filters": [
          {
            "operand": "location",
            "operator": "is",
            "values": ["us-east"]
          }
        ]
      }
    ]
    }
  }'

Deleting a route using the API

You can use the following cURL command to delete a route:

curl -X DELETE <ENDPOINT>/v3/routes/<route_ID> -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

Where

<ENDPOINT>

API endpoint in the region where you plan to configure or manage a route. For more information, see Endpoints.

<route_ID>

ID of the route.

For example, you can use the following cURL request to delete a route with the ID c7673f63-1260-4f86-bc1a-aaedb89391d8:

curl -X DELETE https://api.us-south.logs-router.cloud.ibm.com/v3/routes/c7673f63-1260-4f86-bc1a-aaedb89391d8 -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

Viewing a route using the API

You can use the following cURL command to view the configuration details of 1 route:

curl -X GET <ENDPOINT>/v3/routes/<route_ID> -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

Where

<ENDPOINT>

API endpoint in the region where you plan to configure or manage a route. For more information, see Endpoints.

<route_ID>

ID of the route.

For example, you can run the following cURL request to get information about a route with the ID 00000000-0000-0000-0000-000000000000:

curl -X GET https://api.us-south.logs-router.cloud.ibm.com/v3/routes/c7673f63-1260-4f86-bc1a-aaedb89391d8 -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

Listing all routes using the API

You can use the following cURL command to view all routes:

curl -X GET <ENDPOINT>/v3/routes -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

Where

• <ENDPOINT> is the API endpoint in the region where you plan to configure or manage a route. For more information, see Endpoints.

For example, you can run the following cURL request to get information about the routes that are defined in Dallas:

curl -X GET https://api.us-south.logs-router.cloud.ibm.com/v3/routes -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

HTTP response codes

When you use the IBM Cloud Logs Routing REST API, you can get standard HTTP response codes to indicate whether a method completed successfully.

• A 200 response always indicates success.
• A 4xx response indicates a failure.
• A 5xx response indicates an internal system error.

See the following table for some HTTP response codes: