Data Formats

Results are returned as Content-Type JSON (RFC 7159) or CSV (RFC 4180). Select either format by appending .json or .csv to the query path. Without suffix, JSON is default.

CSV files always include a header containing the requested column names in the requested order. Columns are separated by comma (ASCII 44, UTF-8 0x2C).

When downloading a CSV file you may add an optional filename query argument (ASCII only, 128 characters max, no path separators) which will be used in the Content-Disposition header. Filename suffix .csv is automatically appended if missing.

Compact JSON Arrays

Results on Table and Time Series APIs use an optimized JSON array format that omits object keys to save bandwidth and time. Such responses consist of 2 layers of nested arrays. The outer array contains result rows or time points, the inner arrays hold result columns in the order requested by the columns query parameter.

[
  [
    "BMRdcMqU63QiXmU8vLE7a2qBES1kRX46mTDEGYEUsFV8uL4PDkd",
    "tz1isXamBXpTUgbByQ6gXgZQg4GWNW7r6rKE",
    626160,
    152
  ],[
    "BLhhgCSR8Avhbc7hrqQ9uSsB9Adfts2NwqZbzrGS5VCjxQdLX5N",
    "tz1coHzgoQYRu1Ezn5QChfFEjwTrBzGNQT6U",
    626159,
    152
  ],[
    "BLPUNqkikFAbNDekUhiqJrCaao86o6sPNq5YrcGobHMzSPi4XWr",
    "tz1XfAjZyaLdceHnZxbMYop7g7kWKPut4PR7",
    626158,
    152
  ]
]

info

Note: We sometimes add new fields to tables and time-series data which may change the default order of JSON arrays. To prevent problems, make sure you always use the columns query argument. That way fields you expect are always in the correct order.

JSON Data Types

We use the following data types and encoding conventions throughout the API:

string	unstructured ASCII/UTF-8 text
bytes	binary data encoded as hex string
datetime	UTC timestamps as UNIX milliseconds, e.g. 1536246000000 or ISO 8601/RFC3339 strings 2018-09-06T15:00:00Z
duration	signed 64bit integers with second precision
boolean	a binary value, either as string or number true (1) or false (0)
float64	an IEEE-754 64-bit floating-point number
int64	a signed 64-bit integer (Range: -9,223,372,036,854,775,807 through 9,223,372,036,854,775,807)
uint64	an unsigned 64-bit integer (Range: 0 through 18,446,744,073,709,551,615)
enum	enumerable values expressed as strings, usually used for types
hash	on-chain hashes encoded as base58-check strings
money	monetary quantities are expressed as float64 with 6 decimal points (the Tezos coin unit precision); market endpoints use 5 or more decimal points depending on the fiat or crypto pairs

Timestamps in JSON arrays are encoded as UNIX time at millisecond resolution. That is, value 0 represents Jan 1, 1970 00:00:00 UTC. Timestamps in JSON object responses and CSV output are encoded according to RFC 3339 (2018-09-06T08:07:38Z).

Queries support multiple timestamp formats:

• RFC3339 strings with timezone
• UNIX timestamp in seconds or milliseconds, so 1536246000 and 1536246000000 are equal
• dates without time, i.e. 2018, 2018-09, 2018-09-06 represents midnight at the first day of month and/or month of year
• labels such as now, today, or yesterday to reference a relative points in time
• expressions using now with truncation / offsets, eg. now/d means start of today, now/d-30d means start of day 30 days ago (time units are s, m, h, d)

Status Codes

The TzPro API returns one of the following HTTP status codes. In case of errors, the response body contains additional information encoded as JSON object.

• 200 OK Success
• 400 Bad Request Missing required fields of malformed request data, your fault
• 404 Not Found No such object (block, operation or account has not yet been included in a finalized block)
• 405 Method Not Allowed Unsupported request method
• 409 Conflict Resource state conflict, may happen after reorgs when using a stale block hash as anchor
• 429 Too Many Requests Request limit exceeded
• 500 Internal Server Something went wrong on our end, not your fault
• 502 Bad Gateway Our backend is overloaded or down for maintenance, wait a while before retry
• 503 Service Unavailable Our backend is overloaded or down for maintenance, wait a while before retry
• 504 Gateway Timeout Your request has reached a timeout and was canceled, try to reduce limit or time range in your request

Response Headers

The API returns HTTP response headers with an API version, call runtime and request id to aid debugging, headers to identify the Tezos network and protocol as well as rate limit headers.

# API version
X-Api-Version:   v017-2023-05-31

# Tezos Network (chain id)
X-Network-Id:    NetXdQprcVkpaWU

# Tezos Block Height
X-Chain-Height: 2968198

# Tezos Protocol (protocol hash)
X-Protocol-Hash: PtKathmankSpLLDALzWw7CGD2j2MtyveTwboEYokqUCP4a1LxMg

# Unique request identifier
X-Request-Id: db4cf7d9-7a24-45d6-b37d-ac2fdab6e17c

# Backend runtime
X-Runtime: 0.000131

# Rate limit information
X-Rate-Limit-Group: M
X-Rate-Limit-Limit: 10000
X-Rate-Limit-Remaining: 9994
X-Rate-Limit-Reset: 1638021248

Error Responses

All error messages are JSON encoded. They contain fields numeric and human readable fields to help developers easily debug and map errors.

Schema

Fields	Description
status int	The HTTP status code, duplicated for convenience.
message string	A textual representation of the error status.
scope string	The name of the API call that has failed.
detail string	A detailed text description of the error.
code int	An internal error code.
request_id string	Unique call id that helps us trace failed requests.

Response

{
  "errors": [
    {
      "code": 1007,
      "status": 400,
      "message": "incorrect request syntax",
      "scope": "StreamTable",
      "detail": "unknown column 'cycles'",
      "request_id": "BW-a935b7fedf6beefcedc94e539cfe320cc551c5b3",
    }
  ]
}