GET /v1/segments · API

Day segments hold one market’s minute footprints and minute context for one UTC day. This endpoint lists the days a market has and serves each day as a binary file.

List days

Text

GET /v1/segments/<key>/
HEAD /v1/segments/<key>/

Parameter	In	Description
`key`	Path	Market key, for example `BinanceUsdm_BTCUSDT`. See `/v1/markets`.

The trailing slash is optional: /v1/segments/<key> lists the days too.

Response

Header	Value
`Content-Type`	`text/plain; charset=utf-8`
`Cache-Control`	`no-cache`

One day per line as YYYY-MM-DD, sorted oldest first. A key with no directory gives 200 with an empty body, not 404.

Terminal

curl http://127.0.0.1:8787/v1/segments/BinanceUsdm_BTCUSDT/

Text

Status codes

Status	Body	When
`200`	The list	Valid key
`400`	`bad market key`	The key is empty, 128 characters or longer, or has characters other than ASCII letters, digits, `_` and `-`

Get a day

Text

GET /v1/segments/<key>/<YYYY-MM-DD>.fsd
HEAD /v1/segments/<key>/<YYYY-MM-DD>.fsd

Parameter	In	Description
`key`	Path	Market key
`YYYY-MM-DD`	Path	The UTC day, followed by `.fsd`

Response

Header	Value
`Content-Type`	`application/octet-stream`
`Cache-Control`	Past day: `public, max-age=31536000, immutable`. Today (UTC): `no-cache`.

The body is the day segment, byte for byte as stored. Decode it as described in Segment format. It ends in a checksum, so you can verify a download completely.

Today’s segment grows: the recorder rewrites it every save interval (60 s by default). Flowscope clients ask for it again every two minutes.

Status codes

Status	Body	When
`200`	The segment	The day is recorded
`400`	`bad market key`	Invalid key
`400`	`bad day`	The file name is not `YYYY-MM-DD.fsd` with a valid month (1–12) and day (1–31)
`404`	`not recorded`	Valid key and day, but no such file. Sent with `Cache-Control: no-cache`, so a cache asks again later.

Example

Terminal

curl -fsS -o BinanceUsdm_BTCUSDT-2026-10-03.fsd \
  http://127.0.0.1:8787/v1/segments/BinanceUsdm_BTCUSDT/2026-10-03.fsd
xxd BinanceUsdm_BTCUSDT-2026-10-03.fsd | head -4

Text

00000000: 4653 4431 0200 0000 f950 0000 0000 0000  FSD1.....P......
00000010: 9a99 9999 9999 b93f 0500 0000 0000 0000  .......?........
00000020: 4076 1500 0000 0000 a005 0000 a005 0000  @v..............
00000030: 6c26 0000 a005 0000 ...

The file starts with the magic FSD1, version 2 and codec 0, then the day number (0x50f9 = 20 729 days after 1970-01-01, which is 2026-10-03), the tick size (0.1), the row size in ticks (5), the base tick and the four record counts. The values after the day number are illustrative.

Check whether a day exists without downloading it:

Terminal

curl -sI http://127.0.0.1:8787/v1/segments/Bybit_BTCUSDT/2026-10-03.fsd | head -1

Text

HTTP/1.1 200 OK

Building URLs

Clients build a segment URL from the base URL, the market key and the day:

Text

<base>/v1/segments/<Venue>_<SYMBOL>/<YYYY-MM-DD>.fsd

The day of a timestamp is floor(ms / 86 400 000) days after 1970-01-01, in UTC. Any trailing / on the base is dropped first.

How Flowscope clients use it

For each day a chart wants, a client:

asks the data hub (which runs a recorder), up to four days in flight per market;
merges the segment into its minute store, where the more complete minute wins;
asks again for today after two minutes, and for a missing day after ten minutes;
shows minutes nobody recorded as Unavailable; nothing is fetched from a venue instead.

Clients keep segments in memory for the session only; they are not stored on the machine.