Get Basin Metrics

Retrieve metrics for a specific basin

GET /metrics/

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

Path Parameters

basin · string · required

Basin name to retrieve metrics for

Query Parameters

set · 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

start · integer

Start timestamp as Unix epoch seconds. Required for timeseries metric sets.

end · integer

End timestamp as Unix epoch seconds. Required for timeseries metric sets.

interval · string

Interval to aggregate over for timeseries metric sets. Available values:

• minute
• hour
• day

Response

Returns a MetricSetResponse object containing the requested basin metrics.

values · array

Array of metrics comprising the set. Each metric can be one of four types:

Show Metric Types

scalar · object

Single named value

Show properties

name · string

Metric name

unit · string

Unit of the metric (bytes or operations)

value · number

Metric value

accumulation · object

Named series of (timestamp, value) points representing an accumulation over a specified interval

Show properties

name · string

Timeseries name

unit · string

Unit of the metric (bytes or operations)

interval · string

The interval at which data points are accumulated (minute, hour, or day)

values · array

Array of [timestamp, value] tuples. Each tuple represents the accumulated value for the time period starting at the timestamp, spanning one interval.

gauge · object

Named series of (timestamp, value) points each representing an instantaneous value

Show properties

name · string

Timeseries name

unit · string

Unit of the metric (bytes or operations)

values · array

Array of [timestamp, value] tuples. Each tuple represents the value at the instant of the timestamp.

label · object

Set of string labels

Show properties

name · string

Label name

values · array

Array of string values

cURL - Storage Metrics

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"

Storage Response

{
  "values": [
    {
      "gauge": {
        "name": "storage",
        "unit": "bytes",
        "values": [
          [1704067200, 1073741824],
          [1704070800, 1082130432],
          [1704074400, 1090519040]
        ]
      }
    }
  ]
}

Error Responses

400 · Bad Request

Invalid query parameters, malformed request, or invalid basin name

403 · Forbidden

Invalid or missing authentication token, or insufficient permissions for the basin

408 · Request Timeout

Request took too long to process