Stook Analytics

Learn how to retrieve and analyze storage performance metrics, usage statistics, and access logs for Stook Object Storage.

The Stook Analytics API provides comprehensive programmatic access to your object storage performance metrics, usage statistics, error rates, and raw access logs. This powerful API enables you to:

• Monitor real-time storage performance and reliability

• Build custom dashboards and reporting pipelines

• Perform deep operational analysis

• Integrate analytics data into your existing monitoring systems

• Automate alerting and incident response

These endpoints power the analytics views available in the Medianova Control Panel and offer extensive customization for advanced use cases.

Get Stook Overview Metrics

post

Retrieves high-level metrics for storage buckets to monitor overall system health and performance trends. Results are cached for 60 seconds.

Constraints:

• Maximum allowed date range per request is 90 days.
• Analytics data is retained for 6 months; older ranges may return empty or partial results.
• Bucket names and filter values are strictly validated; SQL keywords and potentially dangerous patterns are not allowed.

Authorizations

Bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

organization_uuidstringRequired

Unique identifier for the organization.

Example: 550e8400-e29b-41d4-a716-446655440000

fromstring · date-timeRequired

Start date/time for metrics retrieval. Must be less than to. The maximum allowed range between from and to is 90 days. Use ISO 8601 date-time format.

Example: 2024-11-12T00:00:00Z

tostring · date-timeRequired

End date/time for metrics retrieval. The maximum allowed range between from and to is 90 days. Use ISO 8601 date-time format.

Example: 2024-11-12T23:59:59Z

bucketsstring[]Optional

List of bucket names to filter results. If omitted or empty, all organization buckets are included. Bucket names can only contain letters, numbers, dots (.), dashes (-), and underscores (_).

Example: ["my-bucket-01"]

timezonestringOptional

Timezone for date conversion in the response.

Default: UTCExample: Europe/Istanbul

metricstring · enumOptional

Primary metric type for the overview calculation.

Example: requestsPossible values:

Responses

200

Successful retrieval of overview metrics.

application/json

401

Unauthorized - Missing or invalid JWT token.

422

Unprocessable Entity - Validation failed (e.g., invalid date range, range exceeds 90 days, invalid bucket name, or invalid filter value).

application/json

post

/api/v2/stook/overview

HTTPcURLJavaScriptPython

POST /api/v2/stook/overview HTTP/1.1
Host: cloud.medianova.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 268

{
  "organization_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "from": "2024-11-12T00:00:00Z",
  "to": "2024-11-12T23:59:59Z",
  "buckets": [
    "my-bucket-01"
  ],
  "filters": [
    {
      "field": "status_code",
      "operator": "in",
      "value": [
        "200",
        "204"
      ]
    }
  ],
  "timezone": "Europe/Istanbul",
  "metric": "requests"
}

{
  "status": true,
  "data": {
    "total_requests": {
      "value": 150000,
      "formatted": "150K",
      "unit": "requests"
    },
    "success_rate": {
      "value": 150000,
      "formatted": "150K",
      "unit": "requests"
    },
    "failure_rate": {
      "value": 150000,
      "formatted": "150K",
      "unit": "requests"
    },
    "avg_response_time": {
      "value": 150000,
      "formatted": "150K",
      "unit": "requests"
    },
    "total_bytes": {
      "value": 150000,
      "formatted": "150K",
      "unit": "requests"
    },
    "download": {
      "value": 150000,
      "formatted": "150K",
      "unit": "requests"
    },
    "upload": {
      "value": 150000,
      "formatted": "150K",
      "unit": "requests"
    }
  }
}

Get Stook Filters

post

Retrieves available analytics filters and their current values (options) for dropdown menus based on the specified time range. Results are cached for 60 seconds.

Constraints:

• Maximum allowed date range per request is 90 days.
• Analytics data is retained for 6 months; older ranges may return empty or partial results.
• Filter inputs are validated to prevent SQL injection; avoid SQL keywords and potentially dangerous patterns.

Authorizations

Bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

organization_uuidstringRequired

Unique identifier for the organization.

Example: 550e8400-e29b-41d4-a716-446655440000

fromstring · date-timeRequired

Start date/time for filter option retrieval. Must be less than to. The maximum allowed range between from and to is 90 days. Use ISO 8601 date-time format.

Example: 2024-11-12T00:00:00Z

tostring · date-timeRequired

End date/time for filter option retrieval. The maximum allowed range between from and to is 90 days. Use ISO 8601 date-time format.

Example: 2024-11-12T23:59:59Z

timezonestringOptional

Timezone for date conversion in the response.

Default: UTCExample: Europe/Istanbul

Responses

200

Successful retrieval of available filters.

application/json

401

Unauthorized - Missing or invalid JWT token.

422

Validation Error - Invalid parameters or date range (including ranges exceeding 90 days).

application/json

post

/api/v2/stook/filters

HTTPcURLJavaScriptPython

POST /api/v2/stook/filters HTTP/1.1
Host: cloud.medianova.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 147

{
  "organization_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "from": "2024-11-12T00:00:00Z",
  "to": "2024-11-12T23:59:59Z",
  "timezone": "Europe/Istanbul"
}

{
  "status": true,
  "data": [
    {
      "field": "api_name",
      "label": "API Name",
      "type": "dropdown",
      "operators": [
        "in",
        "not in"
      ],
      "options": [
        {
          "value": "GetObject",
          "label": "GetObject",
          "count": 15234
        }
      ]
    }
  ]
}

Get Request Histogram

post

Returns a time-series histogram of request counts grouped by the specified interval. Supports multi-bucket analysis and advanced filtering. Results are cached for 60 seconds.

Constraints:

• Maximum allowed date range per request is 90 days.
• Analytics data is retained for 6 months; older ranges may return empty or partial results.
• Bucket names and filter values are strictly validated; SQL keywords and potentially dangerous patterns are not allowed.

Authorizations

Bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

organization_uuidstringRequired

Unique identifier for the organization.

Example: 550e8400-e29b-41d4-a716-446655440000

fromstring · date-timeRequired

Start date/time for histogram retrieval. Must be less than to. The maximum allowed range between from and to is 90 days. Use ISO 8601 date-time format.

Example: 2024-11-12T00:00:00Z

tostring · date-timeRequired

End date/time for histogram retrieval. The maximum allowed range between from and to is 90 days. Use ISO 8601 date-time format.

Example: 2024-11-12T23:59:59Z

intervalstring · enumOptional

Grouping interval. Recommended: 1h for a 1–7 day date range.

Default: 1hExample: 1hPossible values:

bucketsstring[]Optional

Target buckets. If omitted or empty, all buckets are included. Bucket names can only contain letters, numbers, dots (.), dashes (-), and underscores (_).

Example: ["my-bucket-01"]

timezonestringOptional

Timezone for date conversion in the response.

Default: UTCExample: Europe/Istanbul

Responses

200

Successful retrieval of request histogram.

application/json

401

Unauthorized - Missing or invalid JWT token.

422

Unprocessable Entity - Validation failed (e.g., invalid date range, range exceeds 90 days, invalid bucket name, or invalid filter value).

application/json

post

/api/v2/stook/request_histogram

HTTPcURLJavaScriptPython

POST /api/v2/stook/request_histogram HTTP/1.1
Host: cloud.medianova.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 252

{
  "organization_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "from": "2024-11-12T00:00:00Z",
  "to": "2024-11-12T23:59:59Z",
  "interval": "1h",
  "buckets": [
    "my-bucket-01"
  ],
  "filters": [
    {
      "field": "text",
      "operator": "text",
      "value": "text"
    }
  ],
  "timezone": "Europe/Istanbul"
}

{
  "status": true,
  "data": {
    "interval": "1h",
    "total_requests": 150000,
    "data": [
      {
        "timestamp": 1699776000000,
        "datetime": "2024-11-12 00:00:00",
        "count": 12500
      }
    ]
  }
}

Get Error Ratio Histogram

post

Returns time-series data for error ratios (4xx and 5xx) grouped by the specified interval. Supports multi-bucket analysis and advanced filtering. Results are cached for 60 seconds.

Constraints:

• Maximum allowed date range per request is 90 days.
• Analytics data is retained for 6 months; older ranges may return empty or partial results.
• Bucket names and filter values are strictly validated; SQL keywords and potentially dangerous patterns are not allowed.

Authorizations

Bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

organization_uuidstringRequired

Unique identifier for the organization.

Example: 550e8400-e29b-41d4-a716-446655440000

fromstring · date-timeRequired

Start date/time for histogram retrieval. Must be less than to. The maximum allowed range between from and to is 90 days. Use ISO 8601 date-time format.

Example: 2024-11-12T00:00:00Z

tostring · date-timeRequired

End date/time for histogram retrieval. The maximum allowed range between from and to is 90 days. Use ISO 8601 date-time format.

Example: 2024-11-12T23:59:59Z

intervalstring · enumOptional

Time interval for grouping data. Recommended: 1h for a 1–7 day date range.

Default: 1hExample: 1hPossible values:

bucketsstring[]Optional

List of bucket names. If omitted or empty, all organization buckets are included. Bucket names can only contain letters, numbers, dots (.), dashes (-), and underscores (_).

Example: ["my-bucket-01"]

timezonestringOptional

Timezone for date conversion in the response.

Default: UTCExample: Europe/Istanbul

Responses

200

Successful retrieval of error ratio histogram.

application/json

401

Unauthorized - Missing or invalid JWT token.

422

Unprocessable Entity - Validation failed (e.g., invalid date range, range exceeds 90 days, invalid bucket name, or invalid filter value).

application/json

post

/api/v2/stook/error_ratio_histogram

HTTPcURLJavaScriptPython

POST /api/v2/stook/error_ratio_histogram HTTP/1.1
Host: cloud.medianova.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 252

{
  "organization_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "from": "2024-11-12T00:00:00Z",
  "to": "2024-11-12T23:59:59Z",
  "interval": "1h",
  "buckets": [
    "my-bucket-01"
  ],
  "filters": [
    {
      "field": "text",
      "operator": "text",
      "value": "text"
    }
  ],
  "timezone": "Europe/Istanbul"
}

{
  "status": true,
  "data": {
    "interval": "1h",
    "data": [
      {
        "timestamp": 1699776000000,
        "datetime": "2024-11-12 00:00:00",
        "ratio_4xx": 1.2,
        "ratio_5xx": 0.3
      }
    ]
  }
}

Get Stook Charts

post

Returns time-series data points grouped into series for various chart types. Results are cached for 60 seconds.

Constraints:

• Maximum allowed date range per request is 90 days.
• Analytics data is retained for 6 months; older ranges may return empty or partial results.
• Bucket names and filter values are strictly validated; SQL keywords and potentially dangerous patterns are not allowed.

Authorizations

Bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

organization_uuidstringRequired

Unique identifier for the organization.

Example: 550e8400-e29b-41d4-a716-446655440000

fromstring · date-timeRequired

Start date/time for chart retrieval. Must be less than to. The maximum allowed range between from and to is 90 days. Use ISO 8601 date-time format.

Example: 2024-11-12T00:00:00Z

tostring · date-timeRequired

End date/time for chart retrieval. The maximum allowed range between from and to is 90 days. Use ISO 8601 date-time format.

Example: 2024-11-12T23:59:59Z

bucketsstring[]Optional

List of bucket names to filter results. If omitted or empty, all buckets are included. Bucket names can only contain letters, numbers, dots (.), dashes (-), and underscores (_).

Example: ["my-bucket-01"]

intervalstring · enumOptional

Time interval for grouping data points.

Default: 1hExample: 1hPossible values:

chart_typestring · enumOptional

Category for data grouping/dimension.

Default: metricExample: per_bucketPossible values:

metricstring · enumOptional

Metric type to be displayed.

Example: requestsPossible values:

timezonestringOptional

Timezone for date conversion in the response.

Default: UTCExample: Europe/Istanbul

Responses

200

Successful retrieval of chart data.

application/json

401

Unauthorized - Missing or invalid JWT token.

422

Unprocessable Entity - Validation failed (e.g., invalid date range, range exceeds 90 days, invalid bucket name, or invalid filter value).

application/json

post

/api/v2/stook/charts

HTTPcURLJavaScriptPython

POST /api/v2/stook/charts HTTP/1.1
Host: cloud.medianova.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 298

{
  "organization_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "from": "2024-11-12T00:00:00Z",
  "to": "2024-11-12T23:59:59Z",
  "buckets": [
    "my-bucket-01"
  ],
  "interval": "1h",
  "chart_type": "per_bucket",
  "metric": "requests",
  "filters": [
    {
      "field": "text",
      "operator": "text",
      "value": "text"
    }
  ],
  "timezone": "Europe/Istanbul"
}

{
  "status": true,
  "data": {
    "chart_type": "per_bucket",
    "metric": "requests",
    "metric_unit": "requests",
    "interval": "1h",
    "series": [
      {
        "name": "bucket-01",
        "data": [
          {
            "timestamp": 1699776000000,
            "datetime": "2024-11-12 00:00:00",
            "value": 8500,
            "formatted": "8.5K"
          }
        ]
      }
    ]
  }
}

Get Bucket Details

post

Returns a comprehensive list of performance metrics for each bucket within the specified time range. Results are cached for 60 seconds.

Constraints:

• Maximum allowed date range per request is 90 days.
• Analytics data is retained for 6 months; older ranges may return empty or partial results.
• Bucket names and filter values are strictly validated; SQL keywords and potentially dangerous patterns are not allowed.

Authorizations

Bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

organization_uuidstringRequired

Unique identifier for the organization.

Example: 550e8400-e29b-41d4-a716-446655440000

fromstring · date-timeRequired

Start date/time for bucket metrics retrieval. Must be less than to. The maximum allowed range between from and to is 90 days. Use ISO 8601 date-time format.

Example: 2024-11-12T00:00:00Z

tostring · date-timeRequired

End date/time for bucket metrics retrieval. The maximum allowed range between from and to is 90 days. Use ISO 8601 date-time format.

Example: 2024-11-12T23:59:59Z

bucketsstring[]Optional

List of bucket names to filter. If omitted or empty, all organization buckets are included. Bucket names can only contain letters, numbers, dots (.), dashes (-), and underscores (_).

Example: ["my-bucket-01"]

timezonestringOptional

Timezone for date conversion in the response.

Default: UTCExample: Europe/Istanbul

Responses

200

Successful retrieval of bucket details.

application/json

401

Unauthorized - Missing or invalid JWT token.

422

Unprocessable Entity - Validation failed (e.g., invalid date range, range exceeds 90 days, invalid bucket name, or invalid filter value).

application/json

post

/api/v2/stook/bucket_details

HTTPcURLJavaScriptPython

POST /api/v2/stook/bucket_details HTTP/1.1
Host: cloud.medianova.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 236

{
  "organization_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "from": "2024-11-12T00:00:00Z",
  "to": "2024-11-12T23:59:59Z",
  "buckets": [
    "my-bucket-01"
  ],
  "timezone": "Europe/Istanbul",
  "filters": [
    {
      "field": "text",
      "operator": "text",
      "value": "text"
    }
  ]
}

{
  "status": true,
  "data": {
    "buckets": [
      {
        "bucket": "bucket-01",
        "request_count": 150000,
        "request_count_formatted": "150K",
        "io_rate": 1.74,
        "io_rate_formatted": "1.74 req/s",
        "total_bytes": 1073741824,
        "total_bytes_formatted": "1.00 GB",
        "throughput": 12451,
        "throughput_formatted": "12.45 KB/s",
        "success_rate": 98.5,
        "success_rate_formatted": "98.5%",
        "ratio_4xx": 1.2,
        "ratio_4xx_formatted": "1.2%",
        "ratio_5xx": 0.3,
        "ratio_5xx_formatted": "0.3%"
      }
    ]
  }
}

Get Failure Rate Per Bucket

post

Returns time-series failure rate percentages grouped by buckets. Results are cached for 60 seconds.

Constraints:

• Maximum allowed date range per request is 90 days.
• Analytics data is retained for 6 months; older ranges may return empty or partial results.
• Bucket names and filter values are strictly validated; SQL keywords and potentially dangerous patterns are not allowed.

Authorizations

Bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

organization_uuidstringRequired

Unique identifier for the organization.

Example: 550e8400-e29b-41d4-a716-446655440000

fromstring · date-timeRequired

Start date/time for failure-rate retrieval. Must be less than to. The maximum allowed range between from and to is 90 days. Use ISO 8601 date-time format.

Example: 2024-11-12T00:00:00Z

tostring · date-timeRequired

End date/time for failure-rate retrieval. The maximum allowed range between from and to is 90 days. Use ISO 8601 date-time format.

Example: 2024-11-12T23:59:59Z

bucketsstring[]Optional

List of bucket names to analyze. Bucket names can only contain letters, numbers, dots (.), dashes (-), and underscores (_).

Example: ["my-bucket-01","my-bucket-02"]

intervalstring · enumOptional

Time interval for grouping data points.

Default: 1hExample: 1hPossible values:

timezonestringOptional

Timezone for date conversion in the response.

Default: UTCExample: Europe/Istanbul

Responses

200

Successful retrieval of failure rates.

application/json

401

Unauthorized - Missing or invalid JWT token.

422

Unprocessable Entity - Validation failed (e.g., invalid date range, range exceeds 90 days, invalid bucket name, or invalid filter value).

application/json

post

/api/v2/stook/failure_rate_per_bucket

HTTPcURLJavaScriptPython

POST /api/v2/stook/failure_rate_per_bucket HTTP/1.1
Host: cloud.medianova.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 267

{
  "organization_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "from": "2024-11-12T00:00:00Z",
  "to": "2024-11-12T23:59:59Z",
  "buckets": [
    "my-bucket-01",
    "my-bucket-02"
  ],
  "interval": "1h",
  "timezone": "Europe/Istanbul",
  "filters": [
    {
      "field": "text",
      "operator": "text",
      "value": "text"
    }
  ]
}

{
  "status": true,
  "data": {
    "interval": "1h",
    "metric": "failure_rate",
    "metric_unit": "%",
    "series": [
      {
        "name": "bucket-01",
        "data": [
          {
            "timestamp": 1699776000000,
            "datetime": "2024-11-12 00:00:00",
            "value": 1.5,
            "formatted": "1.5%"
          }
        ]
      }
    ]
  }
}

Get Stook Raw Logs

post

Retrieves granular access logs including client info, object paths, and performance metrics. Supports result sorting and multi-page navigation. Results are cached for 60 seconds.

Constraints:

• Maximum allowed date range per request is 90 days.
• Analytics data is retained for 6 months; older ranges may return empty or partial results.
• Bucket names and filter values are strictly validated; SQL keywords and potentially dangerous patterns are not allowed.

Authorizations

Bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

organization_uuidstringRequired

Unique identifier for the organization.

Example: 550e8400-e29b-41d4-a716-446655440000

fromstring · date-timeRequired

Start date/time for raw log retrieval. Must be less than to. The maximum allowed range between from and to is 90 days. Use ISO 8601 date-time format.

Example: 2024-11-12T00:00:00Z

tostring · date-timeRequired

End date/time for raw log retrieval. The maximum allowed range between from and to is 90 days. Use ISO 8601 date-time format.

Example: 2024-11-12T23:59:59Z

bucketsstring[]Optional

Filter by specific buckets. Bucket names can only contain letters, numbers, dots (.), dashes (-), and underscores (_).

Example: ["my-bucket-01"]

limitintegerOptional

Number of records per page.

Default: 100Example: 100

pageintegerOptional

Page number (1-based).

Default: 1Example: 1

sort_fieldstringOptional

Field to sort results by. Commonly ts.

Default: tsExample: ts

sort_orderstring · enumOptional

Sort direction.

Default: descExample: descPossible values:

timezonestringOptional

Timezone for date conversion in the response.

Default: UTCExample: Europe/Istanbul

Responses

200

Successful retrieval of raw logs.

application/json

401

Unauthorized - Missing or invalid JWT token.

422

Unprocessable Entity - Validation failed (e.g., invalid date range, range exceeds 90 days, invalid bucket name, invalid filter value, or invalid pagination inputs).

application/json

post

/api/v2/stook/raw_logs

HTTPcURLJavaScriptPython

POST /api/v2/stook/raw_logs HTTP/1.1
Host: cloud.medianova.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 295

{
  "organization_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "from": "2024-11-12T00:00:00Z",
  "to": "2024-11-12T23:59:59Z",
  "buckets": [
    "my-bucket-01"
  ],
  "limit": 100,
  "page": 1,
  "sort_field": "ts",
  "sort_order": "desc",
  "timezone": "Europe/Istanbul",
  "filters": [
    {
      "field": "text",
      "operator": "text",
      "value": "text"
    }
  ]
}

{
  "status": true,
  "data": {
    "logs": [
      {
        "ts": 1699776000,
        "bucket": "my-bucket",
        "api_name": "GetObject",
        "status_code": 200,
        "object": "/path/to/file.jpg",
        "remote_ip": "192.168.1.1",
        "request_host": "s3.example.com",
        "client_country_code": "TR",
        "client_asn": "AS12345",
        "client_isp": "Example ISP",
        "bytes_sent": 1024000,
        "request_time": 0.125
      }
    ],
    "pagination": {
      "total": 5000,
      "page": 1,
      "limit": 100,
      "total_pages": 50
    }
  }
}