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

# Get Basin Metrics

> Retrieve metrics for a specific basin

## GET /metrics/{basin}

Retrieve usage metrics for a specific basin. This endpoint provides detailed insights into basin-level operations, throughput, and storage.

### Path Parameters

<ParamField path="basin" type="string" required>
  Basin name to retrieve metrics for
</ParamField>

### Query Parameters

<ParamField query="set" type="string" required>
  Metric set to return. Available values:

  * `storage` - Amount of stored data, per hour, aggregated over all streams in the basin
  * `append-ops` - Append operations, per interval
  * `read-ops` - Read operations, per interval
  * `read-throughput` - Read bytes, per interval
  * `append-throughput` - Appended bytes, per interval
  * `basin-ops` - Count of basin RPC operations, per interval
</ParamField>

<ParamField query="start" type="integer">
  Start timestamp as Unix epoch seconds. Required for timeseries metric sets.
</ParamField>

<ParamField query="end" type="integer">
  End timestamp as Unix epoch seconds. Required for timeseries metric sets.
</ParamField>

<ParamField query="interval" type="string">
  Interval to aggregate over for timeseries metric sets. Available values:

  * `minute`
  * `hour`
  * `day`
</ParamField>

### Response

Returns a `MetricSetResponse` object containing the requested basin metrics.

<ResponseField name="values" type="array">
  Array of metrics comprising the set. Each metric can be one of four types:

  <Expandable title="Metric Types">
    <ResponseField name="scalar" type="object">
      Single named value

      <Expandable title="properties">
        <ResponseField name="name" type="string">
          Metric name
        </ResponseField>

        <ResponseField name="unit" type="string">
          Unit of the metric (`bytes` or `operations`)
        </ResponseField>

        <ResponseField name="value" type="number">
          Metric value
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="accumulation" type="object">
      Named series of (timestamp, value) points representing an accumulation over a specified interval

      <Expandable title="properties">
        <ResponseField name="name" type="string">
          Timeseries name
        </ResponseField>

        <ResponseField name="unit" type="string">
          Unit of the metric (`bytes` or `operations`)
        </ResponseField>

        <ResponseField name="interval" type="string">
          The interval at which data points are accumulated (`minute`, `hour`, or `day`)
        </ResponseField>

        <ResponseField name="values" type="array">
          Array of \[timestamp, value] tuples. Each tuple represents the accumulated value for the time period starting at the timestamp, spanning one interval.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="gauge" type="object">
      Named series of (timestamp, value) points each representing an instantaneous value

      <Expandable title="properties">
        <ResponseField name="name" type="string">
          Timeseries name
        </ResponseField>

        <ResponseField name="unit" type="string">
          Unit of the metric (`bytes` or `operations`)
        </ResponseField>

        <ResponseField name="values" type="array">
          Array of \[timestamp, value] tuples. Each tuple represents the value at the instant of the timestamp.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="label" type="object">
      Set of string labels

      <Expandable title="properties">
        <ResponseField name="name" type="string">
          Label name
        </ResponseField>

        <ResponseField name="values" type="array">
          Array of string values
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL - Storage Metrics theme={null}
  curl -X GET "https://aws.s2.dev/v1/metrics/my-basin?set=storage&start=1704067200&end=1704153600&interval=hour" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

  ```bash cURL - Append Operations theme={null}
  curl -X GET "https://aws.s2.dev/v1/metrics/my-basin?set=append-ops&start=1704067200&end=1704153600&interval=minute" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

  ```bash cURL - Read Throughput theme={null}
  curl -X GET "https://aws.s2.dev/v1/metrics/my-basin?set=read-throughput&start=1704067200&end=1704153600&interval=hour" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```
</RequestExample>

<ResponseExample>
  ```json Storage Response theme={null}
  {
    "values": [
      {
        "gauge": {
          "name": "storage",
          "unit": "bytes",
          "values": [
            [1704067200, 1073741824],
            [1704070800, 1082130432],
            [1704074400, 1090519040]
          ]
        }
      }
    ]
  }
  ```

  ```json Append Operations Response theme={null}
  {
    "values": [
      {
        "accumulation": {
          "name": "append-ops",
          "unit": "operations",
          "interval": "minute",
          "values": [
            [1704067200, 142],
            [1704067260, 156],
            [1704067320, 139]
          ]
        }
      }
    ]
  }
  ```

  ```json Read Throughput Response theme={null}
  {
    "values": [
      {
        "accumulation": {
          "name": "read-throughput",
          "unit": "bytes",
          "interval": "hour",
          "values": [
            [1704067200, 524288000],
            [1704070800, 612368640],
            [1704074400, 498860032]
          ]
        }
      }
    ]
  }
  ```
</ResponseExample>

## Error Responses

<ResponseField name="400" type="Bad Request">
  Invalid query parameters, malformed request, or invalid basin name
</ResponseField>

<ResponseField name="403" type="Forbidden">
  Invalid or missing authentication token, or insufficient permissions for the basin
</ResponseField>

<ResponseField name="408" type="Request Timeout">
  Request took too long to process
</ResponseField>