> For the complete documentation index, see [llms.txt](https://docs.silk.us/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.silk.us/api-reference/using-the-api/statistics.md).

# Statistics

Query performance statistics, replication bandwidth statistics, and RPO history.

## Performance stats

The RESTful service exposes Silk performance statistics at the system and volume levels. The API returns one or more data points, starting from the specified time, at the selected resolution: one hour, five minutes, or five seconds. If there are no data points in the specified range and resolution, an empty set is returned.

Each volume object has a `current_stats` property that points to that volume's stats object.

{% hint style="info" %}
Throughput numbers are expressed in bytes.
{% endhint %}

| Modifier (default)         | Description                                                            |
| -------------------------- | ---------------------------------------------------------------------- |
| `__datapoints` (1)         | Number of data points to return, up to 1,000.                          |
| `__from_time` (now)        | Start time, as a Unix timestamp in UTC.                                |
| `__resolution` (`5s`)      | Time delta between data points: `5s`, `5m`, or `1h`.                   |
| `__bs_breakdown` (`false`) | Break down by block size (one entry for each of the four block sizes). |
| `__rw_breakdown` (`false`) | Break down by reads and writes (one entry each).                       |

| Endpoint                                     | Returns                                                                                                                 |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `GET /api/v2/stats/system`                   | System-wide statistics                                                                                                  |
| `GET /api/v2/stats/volumes/{id}`             | Statistics for a single volume                                                                                          |
| `GET /api/v2/stats/volumes?name__in=foo,bar` | Statistics for several volumes. The selection query can use any volume field, even though those fields aren't returned. |

If several data points are requested, multiple results may be returned.

```json
{
  "hits": [
    {
      "iops_avg": 10,
      "iops_max": 120,
      "latency_inner": 1,
      "latency_outer": 1.1,
      "resolution": 5,
      "throughput_avg": 1000,
      "throughput_max": 1200,
      "timestamp": 1437637915,
      "volume": { "ref": "/volumes/5" },
      "volume_name": "foo"
    }
  ],
  "total": 1
}
```

### Examples

| Goal                                                                                                | Request                                                                                             |
| --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| The past day at one-hour resolution for volumes `vol1` and `vol2`                                   | `GET /api/v2/stats/volumes?name__in=vol1,vol2&__datapoints=24&__resolution=1h`                      |
| The last 60 seconds at five-second resolution for all volumes in a volume group                     | `GET /api/v2/stats/volumes?volume_group.ref=/volume_groups/18&__datapoints=12&__resolution=5s`      |
| The last 24 hours at one-hour resolution for every volume, broken down by read/write and block size | `GET /api/v2/stats/volumes?__datapoints=24&__resolution=1h&__bs_breakdown=true&__rw_breakdown=true` |

## Replication stats

The RESTful service exposes replication bandwidth utilization in the same way as performance stats. Resolutions can be one hour, five minutes, or five seconds. If there are no data points in the range, an empty set is returned (for example, when retrieving yesterday's data at five-second resolution). In and out values appear in the same object; there is no in/out breakdown.

Each volume object has a `current_replication_stats` property that points to that volume's replication stats object.

{% hint style="info" %}
Logical and physical in/out numbers are expressed in bytes.
{% endhint %}

Replication stats accept `__datapoints`, `__from_time`, and `__resolution`, with the same defaults as performance stats.

| Endpoint                                                 | Returns                                    |
| -------------------------------------------------------- | ------------------------------------------ |
| `GET /api/v2/replication/stats/system`                   | System-wide replication statistics         |
| `GET /api/v2/replication/stats/volumes/{id}`             | Replication statistics for a single volume |
| `GET /api/v2/replication/stats/volumes?name__in=foo,bar` | Replication statistics for several volumes |

```json
{
  "hits": [
    {
      "physical_in": 10,
      "physical_out": 120,
      "logical_in": 10,
      "logical_out": 120,
      "timestamp": 1437637915,
      "volume": { "ref": "/volumes/5" },
      "volume_name": "foo"
    }
  ],
  "total": 1
}
```

## RPO history

The API exposes a history of replication rounds for each replication session:

* All sessions: `GET /api/v2/replication/rpo_history`
* A specific session: `GET /api/v2/replication/rpo_history/{id}`

By default the API returns the last 100 items, sorted in descending order by `round_start`. Standard filtering is supported, with these modifiers:

| Filter                                                                                                                   | Supported modifiers                           |
| ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------- |
| `session`                                                                                                                | `=`, `__in`                                   |
| `role`                                                                                                                   | `=`, `__in`, `__contains`, `__prefix`         |
| `generation_number`, `round_start`, `round_end`, `target_rpo`, `bytes_transmitted_logical`, `bytes_transmitted_physical` | `=`, `__in`, `__gt`, `__gte`, `__lt`, `__lte` |

{% tabs %}
{% tab title="All sessions" %}

```http
GET /api/v2/replication/rpo_history
```

```json
{
  "hits": [
    {
      "session": { "ref": "/replication_sessions/1" },
      "generation_number": 11,
      "role": "source",
      "round_start": 1437637715,
      "round_end": 1437637915,
      "target_rpo": 300,
      "bytes_transmitted_logical": 1293,
      "bytes_transmitted_physical": 932
    }
  ],
  "total": 1
}
```

{% endtab %}

{% tab title="Filtered" %}
Get rounds where the role is `source` and `bytes_transmitted_logical` is greater than 100.

```http
GET /api/v2/replication/rpo_history?role=source&bytes_transmitted_logical__gt=100
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.silk.us/api-reference/using-the-api/statistics.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
