---
title: "List Flows"
method: GET
path: "/flows"
tags: ["Flows"]
---

# List Flows

`GET /flows`

List the flows registered in the store.

## Query parameters

- `source_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. * `[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.
- `format` 'urn:x-nmos:format:video' | 'urn:x-nmos:format:audio' | 'urn:x-nmos:format:data' | 'urn:x-nmos:format:multi' — Identifies the content format for a flow or source using a URN string.
- `codec` string — MIME Type string.
- `label` string
- `tag.{name}` string
- `tag_exists.{name}` boolean
- `frame_width` integer
- `frame_height` integer
- `page` string
- `limit` integer

## Response `200`

- Flow[]
  - union — Describes a Flow
    - object — Describes a Flow (common properties to all Flows, imported by type-specific specifications)
      - `id` string, required — Flow identifier
      - `source_id` string, required — Source identifier
      - `label` string — Freeform string label for the flow
      - `description` string — Freeform text describing the flow
      - `created_by` string — A string identifier for the entity that created the flow. Implementations SHOULD set suitable default values for `created_by` based on the principal accessing the system, and MAY permit clients to edit the value, subject to suitable permissions-based limitations.
      - `updated_by` string — A string identifier for the entity that updated the flow metadata most recently. Implementations SHOULD set suitable default values for `updated_by` based on the principal accessing the system, and MAY permit clients to edit the value, subject to suitable permissions-based limitations.
      - `tags` Tags — Key value is a freeform string.
      - `metadata_version` string — A change to the flow metadata, not including metadata_version, last_update or segments, results in a new version. If the metadata_version for flow instances is identical then the metadata is identical.
      - `generation` integer — An indication of how many lossy encodings the flow content has been through. A flow with a higher generation may contain less of the original information than a flow with a lower generation.
      - `created` string, date-time — The date-time the flow was created in a given context, e.g. in the store. Implementations SHOULD ignore this if given in a PUT request, and instead manage it internally
      - `metadata_updated` string, date-time — The date-time the flow metadata was updated in a given context, e.g. in the store. Implementations SHOULD ignore this if given in a PUT request, and instead manage it internally
      - `segments_updated` string, date-time — The date-time the flow segments were updated in a given context, e.g. in the store. Implementations SHOULD ignore this if given in a PUT request, and instead manage it internally
      - `read_only` boolean — If set to 'true', implementations SHOULD reject client requests to update Flow metadata (other than the read_only property), Flow Segments and media objects
      - `codec` string, required — A MIME type identification of the (lossy or lossless) coding used for the flow content.
      - `container` string — The container MIME type for flow segments.
      - `avg_bit_rate` integer — The average bit rate of the flow segments in 1000 bits/second. A precise definition can be found in the [Setting Flow Bit Rate Properties](https://github.com/bbc/tams/blob/main/docs/appnotes/0013-setting-flow-bit-rate-properties.md) AppNote.
      - `max_bit_rate` integer — The maximum bit rate of the flow segments in 1000 bits/second. A precise definition can be found in the [Setting Flow Bit Rate Properties](https://github.com/bbc/tams/blob/main/docs/appnotes/0013-setting-flow-bit-rate-properties.md) AppNote.
      - `segment_duration` object — The target flow segment duration in seconds. The duration for each segment may vary around this target value. See also the [Setting Flow Bit Rate Properties](https://github.com/bbc/tams/blob/main/docs/appnotes/0013-setting-flow-bit-rate-properties.md) AppNote for how this property can be used to calculate buffer sizes.
        - `numerator` integer, required — numerator
        - `denominator` integer — denominator
      - `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. * `[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.
      - `flow_collection` Collectionitem[]
        - `id` string, required — Source or Flow Identifier of the member of this collection. Sources must only collect Sources, and Flows must only collect Flows. Must already be registered in TAMS
        - `role` string, required — A human-readable role of the element in this collection (e.g. 'R' to denote a right audio channel in a collection of mono audio Sources)
        - `container_mapping` Containermapping — Defines the location of Flow essence data in a container track
          - `track_index` integer — A zero-based and sequential track index in the container. This assumes a reliable ordering of tracks
          - `format_track_index` integer — A zero-based and sequential track index in the container for a particular Flow format. A container with a video and 2 audio tracks would have a format_track_index 0 for the video Flow and format_track_index 0 and 1 for the audio Flows. This assumes a reliable ordering of tracks for each Flow format
          - `audio_track` object — Mapping for channels in audio tracks to the Flow channels
            - `channel_numbers` integer[] — Array of (zero-based) container channel numbers in Flow order
            - `channel_range` string — Inclusive range of (zero-based) container channel numbers
          - `mp2ts_container` object — Mapping to MPEG-2 Transport Stream containers, ISO/IEC 13818-1 or ITU-T Recommendation H.222.0
            - `pid` integer — The packet ID for the elementary stream packets
          - `mxf_container` object — Mapping to Material Exchange Format containers, SMPTE ST 377-1
            - `package_uid` string — The package UID. Either a SMPTE UMID URN or UUID URN
            - `track_id` integer — The track ID in the package
          - `isobmff_container` object — Mapping to ISO Base Media File Format (e.g. MP4 and MOV) containers, ISO/IEC 14496-12
            - `track_id` integer — The track ID
      - `collected_by` string[] — Flows that reference this Flow to include it in a collection. This attribute is intended to be read-only. Implementations SHOULD ignore this if given in a PUT request, and instead manage it internally
      - `container_mapping` Containermapping — Defines the location of Flow essence data in a container track
        - `track_index` integer — A zero-based and sequential track index in the container. This assumes a reliable ordering of tracks
        - `format_track_index` integer — A zero-based and sequential track index in the container for a particular Flow format. A container with a video and 2 audio tracks would have a format_track_index 0 for the video Flow and format_track_index 0 and 1 for the audio Flows. This assumes a reliable ordering of tracks for each Flow format
        - `audio_track` object — Mapping for channels in audio tracks to the Flow channels
          - `channel_numbers` integer[] — Array of (zero-based) container channel numbers in Flow order
          - `channel_range` string — Inclusive range of (zero-based) container channel numbers
        - `mp2ts_container` object — Mapping to MPEG-2 Transport Stream containers, ISO/IEC 13818-1 or ITU-T Recommendation H.222.0
          - `pid` integer — The packet ID for the elementary stream packets
        - `mxf_container` object — Mapping to Material Exchange Format containers, SMPTE ST 377-1
          - `package_uid` string — The package UID. Either a SMPTE UMID URN or UUID URN
          - `track_id` integer — The track ID in the package
        - `isobmff_container` object — Mapping to ISO Base Media File Format (e.g. MP4 and MOV) containers, ISO/IEC 14496-12
          - `track_id` integer — The track ID
      - `format` 'urn:x-nmos:format:video', required — The primary content type URN for the flow.
      - `essence_parameters` object, required — Describes the parameters of the essence inside this video Flow
        - `frame_rate` object — The fixed number of frames per second. If this parameter is unset, the frame_rate is either unknown or variable.
          - `numerator` integer, required — numerator
          - `denominator` integer — denominator
        - `frame_width` integer, required — The width of the picture in pixels.
        - `frame_height` integer, required — The height of the picture in pixels.
        - `bit_depth` integer — The number of significant bits used to represent the video component sample. If codec is `video/raw`, bit_depth must be set.
        - `interlace_mode` 'progressive' | 'interlaced_tff' | 'interlaced_bff' | 'interlaced_psf' — Interlaced video mode for frames in this Flow
        - `colorspace` 'BT601' | 'BT709' | 'BT2020' | 'BT2100' — Colorspace used for the video
        - `transfer_characteristic` 'SDR' | 'HLG' | 'PQ' — Transfer characteristic
        - `aspect_ratio` object — The display aspect ratio. i.e. display_width / display_height
          - `numerator` integer, required — numerator
          - `denominator` integer, required — denominator
        - `pixel_aspect_ratio` object — The pixel aspect ratio. This is usually 1:1 (i.e. square pixels) for modern video. Some, usually older, video formats use non-square pixels e.g. some Standard Definition video. This is where that may be indicated.
          - `numerator` integer, required — numerator
          - `denominator` integer, required — denominator
        - `component_type` 'YCbCr' | 'RGB' — Picture component representation.
        - `horiz_chroma_subs` integer — Horizontal chroma component sub-sampling. When unc_type is set to a YUV type, horiz_chroma_subs must be set.
        - `vert_chroma_subs` integer — Vertical chroma component sub-sampling. When unc_type is set to a YUV type, vert_chroma_subs must be set.
        - `unc_parameters` object
          - `unc_type` 'planar' | 'YUYV' | 'UYVY' | 'AYUV' | 'v210' | 'v216' | 'RGB' | 'RGBx' | 'xRGB' | 'BGRx' | 'xBGR' | 'RGBA' | 'ARGB' | 'BGRA' | 'ABGR' | 'alpha', required — Uncompressed picture packing type. If codec is `video/raw`, unc_type must be set.
        - `avc_parameters` object
          - `profile` integer, required — AVC / H.264 profile byte. For more information on the use of this property in codec strings, see https://developer.mozilla.org/en-US/docs/Web/Media/Formats/codecs_parameter#using_the_codecs_parameter
          - `level` integer, required — AVC / H.264 level byte. For more information on the use of this property in codec strings, see https://developer.mozilla.org/en-US/docs/Web/Media/Formats/codecs_parameter#using_the_codecs_parameter
          - `flags` integer, required — AVC / H.264 flags byte. For more information on the use of this property in codec strings, see https://developer.mozilla.org/en-US/docs/Web/Media/Formats/codecs_parameter#using_the_codecs_parameter
    - object — Describes a Flow (common properties to all Flows, imported by type-specific specifications)
      - `id` string, required — Flow identifier
      - `source_id` string, required — Source identifier
      - `label` string — Freeform string label for the flow
      - `description` string — Freeform text describing the flow
      - `created_by` string — A string identifier for the entity that created the flow. Implementations SHOULD set suitable default values for `created_by` based on the principal accessing the system, and MAY permit clients to edit the value, subject to suitable permissions-based limitations.
      - `updated_by` string — A string identifier for the entity that updated the flow metadata most recently. Implementations SHOULD set suitable default values for `updated_by` based on the principal accessing the system, and MAY permit clients to edit the value, subject to suitable permissions-based limitations.
      - `tags` Tags — Key value is a freeform string.
      - `metadata_version` string — A change to the flow metadata, not including metadata_version, last_update or segments, results in a new version. If the metadata_version for flow instances is identical then the metadata is identical.
      - `generation` integer — An indication of how many lossy encodings the flow content has been through. A flow with a higher generation may contain less of the original information than a flow with a lower generation.
      - `created` string, date-time — The date-time the flow was created in a given context, e.g. in the store. Implementations SHOULD ignore this if given in a PUT request, and instead manage it internally
      - `metadata_updated` string, date-time — The date-time the flow metadata was updated in a given context, e.g. in the store. Implementations SHOULD ignore this if given in a PUT request, and instead manage it internally
      - `segments_updated` string, date-time — The date-time the flow segments were updated in a given context, e.g. in the store. Implementations SHOULD ignore this if given in a PUT request, and instead manage it internally
      - `read_only` boolean — If set to 'true', implementations SHOULD reject client requests to update Flow metadata (other than the read_only property), Flow Segments and media objects
      - `codec` string, required — A MIME type identification of the (lossy or lossless) coding used for the flow content.
      - `container` string — The container MIME type for flow segments.
      - `avg_bit_rate` integer — The average bit rate of the flow segments in 1000 bits/second. A precise definition can be found in the [Setting Flow Bit Rate Properties](https://github.com/bbc/tams/blob/main/docs/appnotes/0013-setting-flow-bit-rate-properties.md) AppNote.
      - `max_bit_rate` integer — The maximum bit rate of the flow segments in 1000 bits/second. A precise definition can be found in the [Setting Flow Bit Rate Properties](https://github.com/bbc/tams/blob/main/docs/appnotes/0013-setting-flow-bit-rate-properties.md) AppNote.
      - `segment_duration` object — The target flow segment duration in seconds. The duration for each segment may vary around this target value. See also the [Setting Flow Bit Rate Properties](https://github.com/bbc/tams/blob/main/docs/appnotes/0013-setting-flow-bit-rate-properties.md) AppNote for how this property can be used to calculate buffer sizes.
        - `numerator` integer, required — numerator
        - `denominator` integer — denominator
      - `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. * `[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.
      - `flow_collection` Collectionitem[]
        - `id` string, required — Source or Flow Identifier of the member of this collection. Sources must only collect Sources, and Flows must only collect Flows. Must already be registered in TAMS
        - `role` string, required — A human-readable role of the element in this collection (e.g. 'R' to denote a right audio channel in a collection of mono audio Sources)
        - `container_mapping` Containermapping — Defines the location of Flow essence data in a container track
          - `track_index` integer — A zero-based and sequential track index in the container. This assumes a reliable ordering of tracks
          - `format_track_index` integer — A zero-based and sequential track index in the container for a particular Flow format. A container with a video and 2 audio tracks would have a format_track_index 0 for the video Flow and format_track_index 0 and 1 for the audio Flows. This assumes a reliable ordering of tracks for each Flow format
          - `audio_track` object — Mapping for channels in audio tracks to the Flow channels
            - `channel_numbers` integer[] — Array of (zero-based) container channel numbers in Flow order
            - `channel_range` string — Inclusive range of (zero-based) container channel numbers
          - `mp2ts_container` object — Mapping to MPEG-2 Transport Stream containers, ISO/IEC 13818-1 or ITU-T Recommendation H.222.0
            - `pid` integer — The packet ID for the elementary stream packets
          - `mxf_container` object — Mapping to Material Exchange Format containers, SMPTE ST 377-1
            - `package_uid` string — The package UID. Either a SMPTE UMID URN or UUID URN
            - `track_id` integer — The track ID in the package
          - `isobmff_container` object — Mapping to ISO Base Media File Format (e.g. MP4 and MOV) containers, ISO/IEC 14496-12
            - `track_id` integer — The track ID
      - `collected_by` string[] — Flows that reference this Flow to include it in a collection. This attribute is intended to be read-only. Implementations SHOULD ignore this if given in a PUT request, and instead manage it internally
      - `container_mapping` Containermapping — Defines the location of Flow essence data in a container track
        - `track_index` integer — A zero-based and sequential track index in the container. This assumes a reliable ordering of tracks
        - `format_track_index` integer — A zero-based and sequential track index in the container for a particular Flow format. A container with a video and 2 audio tracks would have a format_track_index 0 for the video Flow and format_track_index 0 and 1 for the audio Flows. This assumes a reliable ordering of tracks for each Flow format
        - `audio_track` object — Mapping for channels in audio tracks to the Flow channels
          - `channel_numbers` integer[] — Array of (zero-based) container channel numbers in Flow order
          - `channel_range` string — Inclusive range of (zero-based) container channel numbers
        - `mp2ts_container` object — Mapping to MPEG-2 Transport Stream containers, ISO/IEC 13818-1 or ITU-T Recommendation H.222.0
          - `pid` integer — The packet ID for the elementary stream packets
        - `mxf_container` object — Mapping to Material Exchange Format containers, SMPTE ST 377-1
          - `package_uid` string — The package UID. Either a SMPTE UMID URN or UUID URN
          - `track_id` integer — The track ID in the package
        - `isobmff_container` object — Mapping to ISO Base Media File Format (e.g. MP4 and MOV) containers, ISO/IEC 14496-12
          - `track_id` integer — The track ID
      - `format` 'urn:x-nmos:format:audio', required — The primary content type URN for the flow.
      - `essence_parameters` object, required — Describes the parameters of the essence inside this audio Flow
        - `sample_rate` integer, required — The fixed number of samples per second.
        - `channels` integer, required — The channel count.
        - `bit_depth` integer — The number of significant bits used to represent the audio sample. The minumum number of bytes then equals `round_up(bit_depth / 8)`. If codec is `audio/x-raw-int` bit_depth must be set. If codec is `audio/x-raw-float` bit_depth must be set to 32 or 64
        - `codec_parameters` object
          - `coded_frame_size` integer — The fixed number of samples per coded audio frame.
          - `mp4_oti` integer — The MPEG-4 Object Type Identification. For more information on the use of this property in codec strings, see https://developer.mozilla.org/en-US/docs/Web/Media/Formats/codecs_parameter#mpeg-4_audio
        - `unc_parameters` object
          - `unc_type` 'interleaved' | 'planar' | 'pairs', required — The uncompressed audio multi-channel representation type. If codec is `audio/x-raw-int` or `audio/x-raw-float`, unc_type must be set.
    - object — Describes a Flow (common properties to all Flows, imported by type-specific specifications)
      - `id` string, required — Flow identifier
      - `source_id` string, required — Source identifier
      - `label` string — Freeform string label for the flow
      - `description` string — Freeform text describing the flow
      - `created_by` string — A string identifier for the entity that created the flow. Implementations SHOULD set suitable default values for `created_by` based on the principal accessing the system, and MAY permit clients to edit the value, subject to suitable permissions-based limitations.
      - `updated_by` string — A string identifier for the entity that updated the flow metadata most recently. Implementations SHOULD set suitable default values for `updated_by` based on the principal accessing the system, and MAY permit clients to edit the value, subject to suitable permissions-based limitations.
      - `tags` Tags — Key value is a freeform string.
      - `metadata_version` string — A change to the flow metadata, not including metadata_version, last_update or segments, results in a new version. If the metadata_version for flow instances is identical then the metadata is identical.
      - `generation` integer — An indication of how many lossy encodings the flow content has been through. A flow with a higher generation may contain less of the original information than a flow with a lower generation.
      - `created` string, date-time — The date-time the flow was created in a given context, e.g. in the store. Implementations SHOULD ignore this if given in a PUT request, and instead manage it internally
      - `metadata_updated` string, date-time — The date-time the flow metadata was updated in a given context, e.g. in the store. Implementations SHOULD ignore this if given in a PUT request, and instead manage it internally
      - `segments_updated` string, date-time — The date-time the flow segments were updated in a given context, e.g. in the store. Implementations SHOULD ignore this if given in a PUT request, and instead manage it internally
      - `read_only` boolean — If set to 'true', implementations SHOULD reject client requests to update Flow metadata (other than the read_only property), Flow Segments and media objects
      - `codec` string, required — A MIME type identification of the (lossy or lossless) coding used for the flow content.
      - `container` string — The container MIME type for flow segments.
      - `avg_bit_rate` integer — The average bit rate of the flow segments in 1000 bits/second. A precise definition can be found in the [Setting Flow Bit Rate Properties](https://github.com/bbc/tams/blob/main/docs/appnotes/0013-setting-flow-bit-rate-properties.md) AppNote.
      - `max_bit_rate` integer — The maximum bit rate of the flow segments in 1000 bits/second. A precise definition can be found in the [Setting Flow Bit Rate Properties](https://github.com/bbc/tams/blob/main/docs/appnotes/0013-setting-flow-bit-rate-properties.md) AppNote.
      - `segment_duration` object — The target flow segment duration in seconds. The duration for each segment may vary around this target value. See also the [Setting Flow Bit Rate Properties](https://github.com/bbc/tams/blob/main/docs/appnotes/0013-setting-flow-bit-rate-properties.md) AppNote for how this property can be used to calculate buffer sizes.
        - `numerator` integer, required — numerator
        - `denominator` integer — denominator
      - `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. * `[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.
      - `flow_collection` Collectionitem[]
        - `id` string, required — Source or Flow Identifier of the member of this collection. Sources must only collect Sources, and Flows must only collect Flows. Must already be registered in TAMS
        - `role` string, required — A human-readable role of the element in this collection (e.g. 'R' to denote a right audio channel in a collection of mono audio Sources)
        - `container_mapping` Containermapping — Defines the location of Flow essence data in a container track
          - `track_index` integer — A zero-based and sequential track index in the container. This assumes a reliable ordering of tracks
          - `format_track_index` integer — A zero-based and sequential track index in the container for a particular Flow format. A container with a video and 2 audio tracks would have a format_track_index 0 for the video Flow and format_track_index 0 and 1 for the audio Flows. This assumes a reliable ordering of tracks for each Flow format
          - `audio_track` object — Mapping for channels in audio tracks to the Flow channels
            - `channel_numbers` integer[] — Array of (zero-based) container channel numbers in Flow order
            - `channel_range` string — Inclusive range of (zero-based) container channel numbers
          - `mp2ts_container` object — Mapping to MPEG-2 Transport Stream containers, ISO/IEC 13818-1 or ITU-T Recommendation H.222.0
            - `pid` integer — The packet ID for the elementary stream packets
          - `mxf_container` object — Mapping to Material Exchange Format containers, SMPTE ST 377-1
            - `package_uid` string — The package UID. Either a SMPTE UMID URN or UUID URN
            - `track_id` integer — The track ID in the package
          - `isobmff_container` object — Mapping to ISO Base Media File Format (e.g. MP4 and MOV) containers, ISO/IEC 14496-12
            - `track_id` integer — The track ID
      - `collected_by` string[] — Flows that reference this Flow to include it in a collection. This attribute is intended to be read-only. Implementations SHOULD ignore this if given in a PUT request, and instead manage it internally
      - `container_mapping` Containermapping — Defines the location of Flow essence data in a container track
        - `track_index` integer — A zero-based and sequential track index in the container. This assumes a reliable ordering of tracks
        - `format_track_index` integer — A zero-based and sequential track index in the container for a particular Flow format. A container with a video and 2 audio tracks would have a format_track_index 0 for the video Flow and format_track_index 0 and 1 for the audio Flows. This assumes a reliable ordering of tracks for each Flow format
        - `audio_track` object — Mapping for channels in audio tracks to the Flow channels
          - `channel_numbers` integer[] — Array of (zero-based) container channel numbers in Flow order
          - `channel_range` string — Inclusive range of (zero-based) container channel numbers
        - `mp2ts_container` object — Mapping to MPEG-2 Transport Stream containers, ISO/IEC 13818-1 or ITU-T Recommendation H.222.0
          - `pid` integer — The packet ID for the elementary stream packets
        - `mxf_container` object — Mapping to Material Exchange Format containers, SMPTE ST 377-1
          - `package_uid` string — The package UID. Either a SMPTE UMID URN or UUID URN
          - `track_id` integer — The track ID in the package
        - `isobmff_container` object — Mapping to ISO Base Media File Format (e.g. MP4 and MOV) containers, ISO/IEC 14496-12
          - `track_id` integer — The track ID
      - `format` 'urn:x-nmos:format:data', required — The primary content type URN for the flow.
      - `essence_parameters` object, required — Describes the parameters of the essence inside this data Flow
        - `data_type` string — The type of information encoded in the flow, identified using a URN. e.g. The data_type may be urn:x-tams:data:bounding-box, and the codec `application/json`.
    - object — Describes a Flow (common properties to all Flows, imported by type-specific specifications)
      - `id` string, required — Flow identifier
      - `source_id` string, required — Source identifier
      - `label` string — Freeform string label for the flow
      - `description` string — Freeform text describing the flow
      - `created_by` string — A string identifier for the entity that created the flow. Implementations SHOULD set suitable default values for `created_by` based on the principal accessing the system, and MAY permit clients to edit the value, subject to suitable permissions-based limitations.
      - `updated_by` string — A string identifier for the entity that updated the flow metadata most recently. Implementations SHOULD set suitable default values for `updated_by` based on the principal accessing the system, and MAY permit clients to edit the value, subject to suitable permissions-based limitations.
      - `tags` Tags — Key value is a freeform string.
      - `metadata_version` string — A change to the flow metadata, not including metadata_version, last_update or segments, results in a new version. If the metadata_version for flow instances is identical then the metadata is identical.
      - `generation` integer — An indication of how many lossy encodings the flow content has been through. A flow with a higher generation may contain less of the original information than a flow with a lower generation.
      - `created` string, date-time — The date-time the flow was created in a given context, e.g. in the store. Implementations SHOULD ignore this if given in a PUT request, and instead manage it internally
      - `metadata_updated` string, date-time — The date-time the flow metadata was updated in a given context, e.g. in the store. Implementations SHOULD ignore this if given in a PUT request, and instead manage it internally
      - `segments_updated` string, date-time — The date-time the flow segments were updated in a given context, e.g. in the store. Implementations SHOULD ignore this if given in a PUT request, and instead manage it internally
      - `read_only` boolean — If set to 'true', implementations SHOULD reject client requests to update Flow metadata (other than the read_only property), Flow Segments and media objects
      - `codec` string — A MIME type identification of the (lossy or lossless) coding used for the flow content.
      - `container` string — The container MIME type for flow segments.
      - `avg_bit_rate` integer — The average bit rate of the flow segments in 1000 bits/second. A precise definition can be found in the [Setting Flow Bit Rate Properties](https://github.com/bbc/tams/blob/main/docs/appnotes/0013-setting-flow-bit-rate-properties.md) AppNote.
      - `max_bit_rate` integer — The maximum bit rate of the flow segments in 1000 bits/second. A precise definition can be found in the [Setting Flow Bit Rate Properties](https://github.com/bbc/tams/blob/main/docs/appnotes/0013-setting-flow-bit-rate-properties.md) AppNote.
      - `segment_duration` object — The target flow segment duration in seconds. The duration for each segment may vary around this target value. See also the [Setting Flow Bit Rate Properties](https://github.com/bbc/tams/blob/main/docs/appnotes/0013-setting-flow-bit-rate-properties.md) AppNote for how this property can be used to calculate buffer sizes.
        - `numerator` integer, required — numerator
        - `denominator` integer — denominator
      - `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. * `[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.
      - `flow_collection` Collectionitem[]
        - `id` string, required — Source or Flow Identifier of the member of this collection. Sources must only collect Sources, and Flows must only collect Flows. Must already be registered in TAMS
        - `role` string, required — A human-readable role of the element in this collection (e.g. 'R' to denote a right audio channel in a collection of mono audio Sources)
        - `container_mapping` Containermapping — Defines the location of Flow essence data in a container track
          - `track_index` integer — A zero-based and sequential track index in the container. This assumes a reliable ordering of tracks
          - `format_track_index` integer — A zero-based and sequential track index in the container for a particular Flow format. A container with a video and 2 audio tracks would have a format_track_index 0 for the video Flow and format_track_index 0 and 1 for the audio Flows. This assumes a reliable ordering of tracks for each Flow format
          - `audio_track` object — Mapping for channels in audio tracks to the Flow channels
            - `channel_numbers` integer[] — Array of (zero-based) container channel numbers in Flow order
            - `channel_range` string — Inclusive range of (zero-based) container channel numbers
          - `mp2ts_container` object — Mapping to MPEG-2 Transport Stream containers, ISO/IEC 13818-1 or ITU-T Recommendation H.222.0
            - `pid` integer — The packet ID for the elementary stream packets
          - `mxf_container` object — Mapping to Material Exchange Format containers, SMPTE ST 377-1
            - `package_uid` string — The package UID. Either a SMPTE UMID URN or UUID URN
            - `track_id` integer — The track ID in the package
          - `isobmff_container` object — Mapping to ISO Base Media File Format (e.g. MP4 and MOV) containers, ISO/IEC 14496-12
            - `track_id` integer — The track ID
      - `collected_by` string[] — Flows that reference this Flow to include it in a collection. This attribute is intended to be read-only. Implementations SHOULD ignore this if given in a PUT request, and instead manage it internally
      - `container_mapping` Containermapping — Defines the location of Flow essence data in a container track
        - `track_index` integer — A zero-based and sequential track index in the container. This assumes a reliable ordering of tracks
        - `format_track_index` integer — A zero-based and sequential track index in the container for a particular Flow format. A container with a video and 2 audio tracks would have a format_track_index 0 for the video Flow and format_track_index 0 and 1 for the audio Flows. This assumes a reliable ordering of tracks for each Flow format
        - `audio_track` object — Mapping for channels in audio tracks to the Flow channels
          - `channel_numbers` integer[] — Array of (zero-based) container channel numbers in Flow order
          - `channel_range` string — Inclusive range of (zero-based) container channel numbers
        - `mp2ts_container` object — Mapping to MPEG-2 Transport Stream containers, ISO/IEC 13818-1 or ITU-T Recommendation H.222.0
          - `pid` integer — The packet ID for the elementary stream packets
        - `mxf_container` object — Mapping to Material Exchange Format containers, SMPTE ST 377-1
          - `package_uid` string — The package UID. Either a SMPTE UMID URN or UUID URN
          - `track_id` integer — The track ID in the package
        - `isobmff_container` object — Mapping to ISO Base Media File Format (e.g. MP4 and MOV) containers, ISO/IEC 14496-12
          - `track_id` integer — The track ID
      - `format` 'urn:x-nmos:format:multi', required — The primary content type URN for the flow.

## Other responses

- `400` — Bad request. Invalid query options.

## Changes

- **2025-04-24** `b01aaf8cffe2` — 4 breaking, 8 warning, 35 info
  - removed the enum value `urn:x-tam:format:image` from the `query` request parameter `format`
  - removed 'else' subschema from the `items/oneOf[subschema #1: Video Flow]/allOf[subschema #2]/essence_parameters` response property for the status `200`
  - removed 'if' subschema from the `items/oneOf[subschema #1: Video Flow]/allOf[subschema #2]/essence_parameters` response property for the status `200`
  - removed 'then' subschema from the `items/oneOf[subschema #1: Video Flow]/allOf[subschema #2]/essence_parameters` response property for the status `200`
  - …43 more

[Change history](https://skmtc.dev/aws-samples/apis/time-addressable-media-store/changes/flows/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/b01aaf8cffe2/schema)