Merkl Developer Portal logo
get

/v4/analytics/positions/at/{storingId}

Get closest position states at a timestamp

Return the closest position state(s) to a Unix timestamp for a storingId.

order=DESC (default) returns the last state at or before the timestamp; order=ASC returns the first state at or after it.

A storingId holding decrypted confidential amounts (Zama ERC-7984 plaintext balances) is refused with 403, not emptied — the route serves raw rows, so an empty answer would read as "nothing indexed". A storingId whose processor config cannot be resolved is refused the same way: unresolved metadata is never treated as public.

Each entry mirrors the gRPC StateV2 shape, so the response carries the raw state blob unmodified.

Examples:
- Latest state ≤ T: GET /v4/analytics/positions/at/<storingId>?timestamp=1748635620
- First state ≥ T: GET /v4/analytics/positions/at/<storingId>?timestamp=1748635620&order=ASC
- One specific user: GET /v4/analytics/positions/at/<storingId>?timestamp=1748635620&positionKey=0xUser

Path parameters

storingIdstring
required

The storing/indexing id

Query parameters

timestampnumber | string
required

Target unix timestamp in seconds

orderenum
required
default: DESC

ASC = first state at or after T; DESC = last state at or before T

positionKeystring

Optional position key filter (empty = no filter)

positionGranularityKeystring

Optional sub-position filter, e.g. tokenId (empty = no filter)

Responses

200
Response for status 200
Schema
object
statesobject[]
required
Closest state(s) at or near the requested timestamp, one entry per position
blockNumbernumber
blockTimestampnumber
storingIdstring
positionKeystring
ownerstring
positionGranularityKeystring
stateobject
txHashesstring[]
Example
{
  "states": [
    {
      "blockNumber": 0,
      "blockTimestamp": 0,
      "storingId": "string",
      "positionKey": "string",
      "owner": "string",
      "positionGranularityKey": "string",
      "state": {},
      "txHashes": [
        "string"
      ]
    }
  ]
}