Access

Access events (paginated)

Individual access events, paginated with a keyset cursor over (timestamp, req_id). Pass next_cursor from the previous response back as cursor to fetch the next page. req_id is not unique, so a page is extended rather than allowed to end mid-request — see limit — and a single event is addressed by its event_id.

get/access/events

Request

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

Query parameters

cursorstring

Opaque keyset cursor from the previous page's next_cursor. Omit for the first page.

limitinteger

Target page size (1–1000). Defaults to the endpoint's page size when omitted.

A page may exceed this. req_id is not unique here either, so a page that would end mid-request is extended with that request's remaining rows (up to 512). Ending mid-request is what would make the keyset cursor skip rows. Size a viewport on the rows actually returned.

'5m'
OR
'15m'
OR
'1h'
OR
'6h'
OR
'24h'
OR
'7d'
OR
'14d'
OR
'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.

filter[event_id][in]string[]

Include rows where event_id (opaque per-event id from the events list (exact single-event lookup)) is one of the given values. Repeat the parameter to pass multiple values.

Response

A keyset-paginated page of individual access events.

next_cursorstring

Opaque cursor pointing at the row after the last one in data. Pass it back as cursor to retrieve the next page. Omitted when there are no more rows.

Example response

{
  "data": [
    {
      "event_id": "djE6MTc4Nzc0MzIxNjA1ODoyMkUzMzg3QUEwRjlEM0M2OnFncHptLTBmNWE1OTJm",
      "req_id": "a309e3a8edccb942-AMS",
      "timestamp": "2024-01-14T12:00:00.000Z",
      "method": "POST",
      "uri": "/",
      "status_code": 200,
      "req_time_ms": 63,
      "source": "blockchain-rpc",
      "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
      "gateway_id": "1e06265e-f014-48ae-9cc6-94d046e4e04d",
      "interface_id": "ethereum-mainnet-json-rpc",
      "chain": "ethereum",
      "network": "ethereum-mainnet",
      "region": "europe-west4",
      "bytes_sent": 1024,
      "bytes_read": 256,
      "remote_ip": "203.0.113.42",
      "ua": "tatum-sdk/4.2.0",
      "batch_size": 1,
      "host": "ethereum-mainnet.gateway.tatum.io",
      "error_reason": "ip_not_allowed"
    }
  ],
  "next_cursor": "eyJ0cyI6IjIwMjQtMDEtMTRUMTI6MDA6MDBaIiwicmVxX2lkIjoiYWJjLTEyMyJ9"
}

Changes

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