---
title: "List Flow Segments"
method: GET
path: "/flows/{flowId}/segments"
tags: ["FlowSegments"]
---

# List Flow Segments

`GET /flows/{flowId}/segments`

Returns the Flow Segments.

The Flow Segment provides information about the Media Object.
The Storage Backend type, which is indicated in the [/service/storage-backends](#/operations/GET_storage-backends) resource, determines the information that is included in the response to allow the Flow Segment's Media Object to be downloaded by the client.
The examples provided here are for the "http_object_store" Storage Backend type which MUST include a `get_urls` property that contains the HTTP URLs for downloading the Media Object - service implementations should generate this internally.

The Flow Segment may include timing adjustment information that the client needs to apply when extracting the samples from the Media Object.
The timestamp of a sample on the Flow Segment's timeline (`segment_ts`) is the timestamp of that sample embedded in or derived from the internal timing of the Media Object (`media_object_ts`) adjusted by `ts_offset`: `segment_ts = media_object_ts + ts_offset`.

It may also use a subset of the samples in the Media Object, and if the `include_object_timerange=true` parameter is set, the object's timerange will also be returned to aid identifying which samples to skip.

Segments are sorted by timerange, in ascending order by default.
As Segments in TAMS do not overlap, either of the start or end timestamp of the timerange may be used as the sort key.
Service implementations MUST take clusivity markers of the timerange into account.
Service implementations should consider edge cases such as a timerange with an exclusive end `[1:0_2:0)` followed by an instantaneous timerange of `[2:0]`.

Clients should use the pagination options to limit the results to a timerange and/or count.
Service implementations may also limit the results returned.
This will be signalled via the paging headers in the response.
The list of Flow Segments can be empty.
A request for Segments from a non-existent Flow will return an empty list, not a 404.

Note that for codecs with temporal re-ordering, the timerange representes the _presentation_ timeline, and clients may need to check the `key_frame_count` property and/or read backwards from the start of the requested timerange to retrieve enough reference material to start decoding.

Where Flow Segments reference initialisation segment Objects with the same ID, the initialisation segment is the same.
Consuming clients may choose to ignore initialisation segment Objects that haven't changed in subsequent Flow Segments.

When making requests to provided `get_url`s that are not presigned, clients SHOULD include credentials if the provided URL is on the same origin as the Service itself, akin to the `same-origin` mode in the [WhatWG Fetch Standard](https://fetch.spec.whatwg.org/#concept-request-credentials-mode). Services MAY support the use of out-of-band credentials where the provided URL is on a different origin to the Service itself. Services SHOULD NOT solely require the use of out-of-band credentials.

## Query parameters

- `object_id` string
- `timerange` string — A timerange of timestamps. It is represented using one or two timestamps with inclusivity and exclusivity markers. E.g. * `[0:0_10:0)` represents 10 seconds of media starting at timestamp `0:0` and ending before `10:0`. * `(5:0_` represents a timerange starting after `5:0` and to eternity. * `_` without timestamps or inclusivity markers represents "eternity" (i.e. the entire timeline). * `()` without timestamps represents "never" (i.e. a range of zero length in no particular position). * `[1694429247:0_1694429248:0)` is a 1 second TAI timerange starting at 2023-09-11T10:46:50.0Z UTC. * `[1694429247:0]` is an instantaneous TAI timerange at 2023-09-11T10:46:50.0Z UTC. This is equivalent to `[1694429247:0_1694429247:0]`. The short syntax is preferred due to ease of identification as instantaneous. Instantaneous TimeRanges cannot use exclusive markers (i.e. `(` or `)`). * A `[` or `]` indicates that bound is inclusive, and a `(` or `)` indicates that bound is exclusive. Details of the format can be found in the [Timestamps in TAMS](https://github.com/bbc/tams/blob/main/docs/appnotes/0008-timestamps-in-TAMS.md) application note.
- `reverse_order` boolean
- `verbose_storage` boolean
- `accept_get_urls` string — A list of Object GET URL Labels, formatted for use in query string parameters
- `accept_storage_ids` string — A list of Universally Unique Identifiers (UUIDs) as defined in [RFC9562](https://www.rfc-editor.org/rfc/rfc9562), formatted for use in query string parameters
- `presigned` boolean
- `storage_backend_tag.{name}` string
- `storage_backend_tag_exists.{name}` boolean
- `include_object_timerange` boolean
- `page` string
- `limit` integer

## Response `200`

- Flowsegment[]
  - `object_id` string, required — The object store identifier for the Media Object.
  - `ts_offset` string — A signed nanosecond resolution timestamp represented as "{sign?}{seconds}:{nanoseconds}". The intended interpretation of the value is assumed to be defined elsewhere. E.g. * "1:40000000" is the timestamp of the 27th video frame for 25 Hz video with origin at "0:0". * "1694429247:40000000" is the TAI timestamp for a video frame at 2023-09-11T10:46:50.04Z UTC. Details of the format can be found in the [Timestamps in TAMS](https://github.com/bbc/tams/blob/main/docs/appnotes/0008-timestamps-in-TAMS.md) application note.
  - `timerange` string, required — A timerange of timestamps. It is represented using one or two timestamps with inclusivity and exclusivity markers. E.g. * `[0:0_10:0)` represents 10 seconds of media starting at timestamp `0:0` and ending before `10:0`. * `(5:0_` represents a timerange starting after `5:0` and to eternity. * `_` without timestamps or inclusivity markers represents "eternity" (i.e. the entire timeline). * `()` without timestamps represents "never" (i.e. a range of zero length in no particular position). * `[1694429247:0_1694429248:0)` is a 1 second TAI timerange starting at 2023-09-11T10:46:50.0Z UTC. * `[1694429247:0]` is an instantaneous TAI timerange at 2023-09-11T10:46:50.0Z UTC. This is equivalent to `[1694429247:0_1694429247:0]`. The short syntax is preferred due to ease of identification as instantaneous. Instantaneous TimeRanges cannot use exclusive markers (i.e. `(` or `)`). * A `[` or `]` indicates that bound is inclusive, and a `(` or `)` indicates that bound is exclusive. Details of the format can be found in the [Timestamps in TAMS](https://github.com/bbc/tams/blob/main/docs/appnotes/0008-timestamps-in-TAMS.md) application note.
  - `last_duration` string — A signed nanosecond resolution timestamp represented as "{sign?}{seconds}:{nanoseconds}". The intended interpretation of the value is assumed to be defined elsewhere. E.g. * "1:40000000" is the timestamp of the 27th video frame for 25 Hz video with origin at "0:0". * "1694429247:40000000" is the TAI timestamp for a video frame at 2023-09-11T10:46:50.04Z UTC. Details of the format can be found in the [Timestamps in TAMS](https://github.com/bbc/tams/blob/main/docs/appnotes/0008-timestamps-in-TAMS.md) application note.
  - `object_timerange` string — A timerange of timestamps. It is represented using one or two timestamps with inclusivity and exclusivity markers. E.g. * `[0:0_10:0)` represents 10 seconds of media starting at timestamp `0:0` and ending before `10:0`. * `(5:0_` represents a timerange starting after `5:0` and to eternity. * `_` without timestamps or inclusivity markers represents "eternity" (i.e. the entire timeline). * `()` without timestamps represents "never" (i.e. a range of zero length in no particular position). * `[1694429247:0_1694429248:0)` is a 1 second TAI timerange starting at 2023-09-11T10:46:50.0Z UTC. * `[1694429247:0]` is an instantaneous TAI timerange at 2023-09-11T10:46:50.0Z UTC. This is equivalent to `[1694429247:0_1694429247:0]`. The short syntax is preferred due to ease of identification as instantaneous. Instantaneous TimeRanges cannot use exclusive markers (i.e. `(` or `)`). * A `[` or `]` indicates that bound is inclusive, and a `(` or `)` indicates that bound is exclusive. Details of the format can be found in the [Timestamps in TAMS](https://github.com/bbc/tams/blob/main/docs/appnotes/0008-timestamps-in-TAMS.md) application note.
  - `sample_offset` integer — The start of the Segment represented as a count of samples from the start of the Media Object. Note that a sample is a video frame or audio sample. A (coded) audio frame has multiple audio samples. Assumed to be 0 if not set. DEPRECATED: Use object_timerange instead - see AppNote 0036. Service implementations SHOULD continue to store and return it if set.
  - `sample_count` integer — The count of samples in the Segment (which may be fewer than in the Media Object). The count could be less than expected given the Segment duration and rate if there are gaps. If not set, every sample from sample_offset onwards is used. Note that a sample is a video frame or audio sample. A (coded) audio frame has multiple audio samples. DEPRECATED: Use object_timerange instead - see AppNote 0036. Service implementations SHOULD continue to store and return it if set.
  - `init_object` object — Provides the location and metadata of the files corresponding to a Object.
    - `object_id` string, required — The identifier of the initialisation Object.
    - `get_urls` object[] — A list of URLs to which a GET request can be made to directly retrieve the contents of the Object. This is required by the `http_object_store` Storage Backend type, which is the only one currently described. Clients may choose any URL in the list and treat the content returned as identical, however servers may sort the list such that the preferred URL is first. Storage Backend metadata for controlled URLs should be populated by the TAMS instance based on the Storage Backend the Object instance resides in.
      - `store_type` 'http_object_store' — The generic Storage Backend type. Used to identify the required workflow for reading and writing media. Any `store_product` should be compatible, as much is required for basic interoperability between TAMS implementations, with their associated generic `store_type`.
      - `provider` string — The cloud (or other) provider of the Storage Backend
      - `region` string — The region in the cloud this Storage Backend resides
      - `availability_zone` string — The availability zone in the cloud region this Storage Backend resides. Note that many cloud providers randomize availability zone identifiers such that they are consistent within a cloud account, but not necessarily between accounts. Caution should be exercised when using this parameter.
      - `store_product` string — The storage product name.
      - `tags` Tags — Key is a freeform string. Value is a freeform string, or an array of freeform strings.
      - `storage_id` string — A Universally Unique Identifier (UUID) as defined in [RFC9562](https://www.rfc-editor.org/rfc/rfc9562)
      - `url` string, required — A URL to which a GET request can be made to directly retrieve the contents of the Object. Clients should include credentials if the provide URL is on the same origin as the API endpoint. This URL SHOULD support the inclusion of checksums in headers as supported by advertised Storage Backend product. See AppNote 0048 for more details.
      - `presigned` boolean — If `true`, this URL is pre-signed. If this parameter is unset, the URL is NOT pre-signed. The presigned URL SHALL remain valid for the timeframe advertised in [`min_presigned_url_timeout` at the `/service`](#/operations/GET_service) endpoint, which is subject to a specified minimum (see service endpoint schema).
      - `label` string — Label identifying this URL. If the URL is controlled by the service instance, this is the Storage Backend's label. If the URL is uncontrolled, this is the label provided when a client registered the URL. If the 'label' is not set then this URL can't be filtered for using the 'accept_get_urls' API query parameter.
      - `controlled` boolean — If `true`, this URL is on a Storage Backend controlled by this service instance. If `false`, this URL is uncontrolled and does not have it's lifecycle managed by this instance. If this parameter is unset, assume `true`.
  - `key_frame_count` integer — The number of key frames in the Media Object. This should be set greater than zero when the Media Object contains key frames that serve as a stream access point
  - `get_urls` object[] — A list of URLs to which a GET request can be made to directly retrieve the contents of the Object. This is required by the `http_object_store` Storage Backend type, which is the only one currently described. Clients may choose any URL in the list and treat the content returned as identical, however servers may sort the list such that the preferred URL is first. Storage Backend metadata for controlled URLs should be populated by the TAMS instance based on the Storage Backend the Object instance resides in.
    - `store_type` 'http_object_store' — The generic Storage Backend type. Used to identify the required workflow for reading and writing media. Any `store_product` should be compatible, as much is required for basic interoperability between TAMS implementations, with their associated generic `store_type`.
    - `provider` string — The cloud (or other) provider of the Storage Backend
    - `region` string — The region in the cloud this Storage Backend resides
    - `availability_zone` string — The availability zone in the cloud region this Storage Backend resides. Note that many cloud providers randomize availability zone identifiers such that they are consistent within a cloud account, but not necessarily between accounts. Caution should be exercised when using this parameter.
    - `store_product` string — The storage product name.
    - `tags` Tags — Key is a freeform string. Value is a freeform string, or an array of freeform strings.
    - `storage_id` string — A Universally Unique Identifier (UUID) as defined in [RFC9562](https://www.rfc-editor.org/rfc/rfc9562)
    - `url` string, required — A URL to which a GET request can be made to directly retrieve the contents of the Object. Clients should include credentials if the provide URL is on the same origin as the API endpoint. This URL SHOULD support the inclusion of checksums in headers as supported by advertised Storage Backend product. See AppNote 0048 for more details.
    - `presigned` boolean — If `true`, this URL is pre-signed. If this parameter is unset, the URL is NOT pre-signed. The presigned URL SHALL remain valid for the timeframe advertised in [`min_presigned_url_timeout` at the `/service`](#/operations/GET_service) endpoint, which is subject to a specified minimum (see service endpoint schema).
    - `label` string — Label identifying this URL. If the URL is controlled by the service instance, this is the Storage Backend's label. If the URL is uncontrolled, this is the label provided when a client registered the URL. If the 'label' is not set then this URL can't be filtered for using the 'accept_get_urls' API query parameter.
    - `controlled` boolean — If `true`, this URL is on a Storage Backend controlled by this service instance. If `false`, this URL is uncontrolled and does not have it's lifecycle managed by this instance. If this parameter is unset, assume `true`.

## Other responses

- `400` — Bad request. Invalid query options.
- `404` — The Flow ID in the path is invalid.

## Changes

- **2026-08-25** `eb3977b33601` — 4 info
  - added the new optional `query` request parameter `storage_backend_tag.{name}`
  - added the new optional `query` request parameter `storage_backend_tag_exists.{name}`
  - added the optional property `items/allOf[subschema #1]/init_object/allOf[subschema #2: Object]/get_urls/items/allOf[subschema #1: Storage Backend]/tags` to the response with the `200` status
  - added the optional property `items/allOf[subschema #2: Object]/allOf[subschema #2: Object]/get_urls/items/allOf[subschema #1: Storage Backend]/tags` to the response with the `200` status
- **2026-07-10** `7a9a5cdbb3d2` — 3 info
  - added the optional property `items/allOf[subschema #1]/init_object` to the response with the `200` status
  - added `#/components/schemas/objectmediacore` to the `items/` response property `allOf` list for the response status `200`
  - removed `#/components/schemas/objectcore` from the `items/` response property `allOf` list for the response status `200`
- **2025-10-21** `4c8d2bfcb854` — 4 info
  - added the new optional `query` request parameter `include_object_timerange`
  - added the optional property `items/allOf[subschema #1]/object_timerange` to the response with the `200` status
  - response property `items/allOf[subschema #1]/sample_count` deprecated
  - response property `items/allOf[subschema #1]/sample_offset` deprecated
- …earlier changes not shown

[Full history](https://skmtc.dev/aws-samples/apis/time-addressable-media-store/changes/flows/:flowId/segments/get.md)

---

[API](https://skmtc.dev/aws-samples/apis/time-addressable-media-store.md) · [All operations](https://skmtc.dev/aws-samples/apis/time-addressable-media-store/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/aws-samples/time-addressable-media-store/revisions/eb3977b33601/schema)