> ## Documentation Index
> Fetch the complete documentation index at: https://docs.creditbenchmark.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scope and Empty Results

> How scope and result_filter narrow Credit Benchmark Analytics API queries, and why a successful request can still return an empty result set.

Analytics requests separate **input selection** from **output shaping**.

* **`scope`** defines which entities enter the analytic.
* **`result_filter`** shapes the rows returned after the analytic runs.

For route selection, see [Choosing a route](/api-reference/analytics-endpoints). For `metric` and `rating_scale`, see [Metrics and scales](/api-reference/metrics-and-rating-scales).

## Scope

`scope` is evaluated before the endpoint computes its result.

<Tabs>
  <Tab title="Portfolio scope">
    Use `scope.portfolio` when you already know the entities.

    ```json theme={null}
    {
      "scope": {
        "portfolio": {
          "CB_ID": ["CB0000022706", "CB0000022177"]
        }
      }
    }
    ```

    Custom portfolio columns can be used as `facet_column` values where the endpoint supports facets.
  </Tab>

  <Tab title="Filter scope">
    Use `scope.filters` when the API should build the universe from field conditions.

    ```json theme={null}
    {
      "scope": {
        "filters": [
          {
            "key": "CB_Country",
            "operator": "==",
            "values": "United States"
          },
          {
            "key": "CB_CCR_21_Notch",
            "operator": ">=",
            "values": 8
          }
        ]
      }
    }
    ```

    If `filters_join` is omitted, multiple filters are joined with AND.
  </Tab>

  <Tab title="Portfolio and filters">
    When both are supplied, the route uses the **intersection**.

    ```json theme={null}
    {
      "scope": {
        "portfolio": {
          "CB_ID": ["CB0000022706", "CB0000022177"]
        },
        "filters": [
          {
            "key": "CB_Sector",
            "operator": "==",
            "values": "Banks"
          }
        ]
      }
    }
    ```

    This means entities in your portfolio that are Banks, not your portfolio plus all Banks.
  </Tab>

  <Tab title="Filter join syntax">
    Use `filters_join` only when you need explicit OR or NOT logic. It is positional and has one more item than `filters`.

    ```json theme={null}
    {
      "scope": {
        "filters": [
          {
            "key": "CB_Country",
            "operator": "==",
            "values": "United States"
          },
          {
            "key": "CB_Sector",
            "operator": "==",
            "values": "Banks"
          }
        ],
        "filters_join": ["", "|", ""]
      }
    }
    ```
  </Tab>
</Tabs>

## Result filter

`result_filter` does not change the input universe. It only filters, sorts, or limits computed output rows.

| Mechanism               | Applies to                        |
| ----------------------- | --------------------------------- |
| `scope.filters`         | Entities before the analytic runs |
| `result_filter.filters` | Rows after the analytic runs      |
| `result_filter.sort`    | Row order in the response         |
| `result_filter.limit`   | Maximum rows returned             |

Use `scope` to decide what goes in. Use `result_filter` to decide what comes back.

## MyRating coverage

With `metric: "CCR"`, the analytic uses scoped entities that have consensus data.

With `metric: "MyRating"`, the analytic uses only the part of your scope where your bank has submitted ratings for the requested date window.

In other words, selecting `MyRating` can reduce the universe from "everything you requested" to "the requested entities **your bank has rated**." If your bank has not rated any entities in the requested scope, the API returns an empty success response rather than an error.

| Requested scope | Your bank's coverage | MyRating uses          |
| --------------- | -------------------- | ---------------------- |
| 3 entities      | 3 rated entities     | 3 entities             |
| 3 entities      | 2 rated entities     | 2 entities             |
| 3 entities      | 0 rated entities     | Empty success response |

For aggregate-style MyRating routes, ex-me fields are calculated for that same covered subset. They are not a full-scope benchmark for entities your bank does not rate.

Do not compare `AGG_EntityCount` from `CCR` responses with `AGG_ClientEntityCount` from `MyRating` responses as if they share the same denominator.

## Empty response by route

| Route                                          | Empty success response         |
| ---------------------------------------------- | ------------------------------ |
| `getdata`                                      | `{}` or empty column arrays    |
| `aggregatetrend`                               | `{}`                           |
| `creditbreakdown`                              | `{}`                           |
| `entityratingchange`                           | `{}`                           |
| `ratingdistribution` with `metric: "CCR"`      | `{"ccr": {}}`                  |
| `ratingdistribution` with `metric: "MyRating"` | `{"my_bank": {}, "ex_me": {}}` |