Access

Access breakdown

Where the window's requests went: the top 10 networks plus one "other" total, the top status codes and methods, the top 10 client IPs (each with its error rate and egress) plus one "other" total, every traffic source with a trend, and p50/p90/p95 latency over time — for the same window, source and filters as /access/chart, so a zoom updates it. Shares are of total_requests in the same response. Source sparklines share the KPI sparklines' grid (at most 30 points, sources_step_ms wide); the latency series has its own of at most 60. Accepts every filter[...] field /access/events does except event_id, plus search. When a raw read trips its bound the response is capped: true: total_requests and every *_other are null and the lists are empty.

get/access/breakdown

Request

Base URL
https://api.tatum.io/v4/logs
URL
https://api.tatum.io/v4/logs/access/breakdown
Auth
API key in header x-api-key

Query parameters

'5m'

'15m'

'1h'

'6h'

'24h'

'7d'

'14d'

'30d'

Relative look-back window. Ignored when from/to are supplied.

fromstring date-time

Inclusive window start, ISO-8601. Use together with to for an explicit range instead of time_range.

tostring date-time

Exclusive window end, ISO-8601. Defaults to now when only from is given.

searchstring

Free-text substring match against the request URI. Matched with lower(uri) LIKE '%needle%', so separators (/, -, _, ., :) are fine. Control bytes are rejected; min 3 chars, max 128.

On an aggregate endpoint a search is answered from the raw table, whose read is bounded: past ACCESS_RAW_ROW_CAP rows scanned the response is capped: true. The floor is not cosmetic: access_logs_v1 has no index on uri, so a 1–2 char needle scans the owner's slice for a match that would hit nearly every row.

filter[status_code][in]integer[]

Include rows where status_code (HTTP response status code) is one of the given values. Repeat the parameter to pass multiple values.

filter[status_code][nin]integer[]

Exclude rows where status_code (HTTP response status code) is none of the given values. Repeat the parameter to pass multiple values.

filter[status_code][between]integer[]

Include rows where status_code (HTTP response status code) falls within an inclusive numeric range (SQL BETWEEN lo AND hi). Pass the parameter exactly twice: first the lower bound, then the upper bound.

filter[network][in]string[]

Include rows where network (blockchain network (chain-qualified)) is one of the given values. Repeat the parameter to pass multiple values. Pass (empty) to match rows with no network (unattributed traffic).

filter[network][nin]string[]

Exclude rows where network (blockchain network (chain-qualified)) is none of the given values. Repeat the parameter to pass multiple values. Pass (empty) to match rows with no network (unattributed traffic).

filter[chain][in]string[]

Include rows where chain (blockchain — the parent of network) is one of the given values. Repeat the parameter to pass multiple values. Pass (empty) to match rows with no chain (unattributed traffic).

filter[chain][nin]string[]

Exclude rows where chain (blockchain — the parent of network) is none of the given values. Repeat the parameter to pass multiple values. Pass (empty) to match rows with no chain (unattributed traffic).

filter[method][in]string[]

Include rows where method (HTTP / RPC method) is one of the given values. Repeat the parameter to pass multiple values.

filter[method][nin]string[]

Exclude rows where method (HTTP / RPC method) is none of the given values. Repeat the parameter to pass multiple values.

filter[method][contains]string

Include rows where method (HTTP / RPC method) contains this substring (SQL LIKE '%value%').

filter[remote_ip][in]string[]

Include rows where remote_ip (client IP address, IPv4 or IPv6 (IPv6 matched in canonical form)) is one of the given values. Repeat the parameter to pass multiple values.

filter[remote_ip][nin]string[]

Exclude rows where remote_ip (client IP address, IPv4 or IPv6 (IPv6 matched in canonical form)) is none of the given values. Repeat the parameter to pass multiple values.

filter[source][in]string[]

Include rows where source (traffic source / attribution channel) is one of the given values. Repeat the parameter to pass multiple values. Pass (empty) to match rows with no source (unattributed traffic).

filter[source][nin]string[]

Exclude rows where source (traffic source / attribution channel) is none of the given values. Repeat the parameter to pass multiple values. Pass (empty) to match rows with no source (unattributed traffic).

filter[req_id][in]string[]

Include rows where req_id (request id — NOT unique, may match unrelated requests) is one of the given values. Repeat the parameter to pass multiple values.

Response

Requests by network, status code, method, client IP and source, and latency percentiles over time.

total_requestsnumber nullable required

Requests in the window — the denominator of every share_pct. null when capped: the raw read bound counts rows scanned, not rows matched.

sources_step_msnumber required

Width of each source sparkline point: the KPI sparklines' grid of at most 30 points from the window start, a whole multiple of the chart's bucket_ms. Set also when capped.

cappedboolean required

True when the window was answered from the raw table and a read stopped at ACCESS_RAW_ROW_CAP rows scanned.

Example response

{
  "total_requests": 184230,
  "networks": [
    {
      "network": "ethereum-mainnet",
      "chain": "ethereum",
      "requests": 1503,
      "share_pct": 30.08
    }
  ],
  "networks_other": {
    "requests": 1503,
    "share_pct": 30.08
  },
  "statuses": [
    {
      "status_code": 200,
      "requests": 1503,
      "share_pct": 30.08
    }
  ],
  "statuses_other": {
    "requests": 1503,
    "share_pct": 30.08
  },
  "methods": [
    {
      "method": "POST",
      "requests": 1503,
      "share_pct": 30.08
    }
  ],
  "methods_other": {
    "requests": 1503,
    "share_pct": 30.08
  },
  "ips": [
    {
      "remote_ip": "203.0.113.42",
      "requests": 1503,
      "share_pct": 30.08,
      "error_rate_pct": 1.2,
      "egress_bytes": 1048576
    }
  ],
  "ips_other": {
    "requests": 1503,
    "share_pct": 30.08
  },
  "sources": [
    {
      "source": "blockchain-rpc",
      "requests": 1503,
      "share_pct": 30.08,
      "sparkline": [
        {
          "timestamp": "2024-01-14T12:00:00.000Z",
          "value": 42
        }
      ]
    }
  ],
  "latency": {
    "points": [
      {
        "timestamp": "2024-01-14T12:00:00.000Z"
      }
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.