---
title: "POST /GetComposition"
method: POST
path: "/GetComposition"
---

# POST /GetComposition

`POST /GetComposition`

Get information about the specified Composition resource.

## Request body

- object
  - `arn` string, required — ARN of the Composition resource.

## Response `200`

Success

- GetCompositionResponse
  - `composition` object — The Composition that was returned.
    - `arn` string, required — ARN of the Composition resource.
    - `stageArn` string, required — ARN of the stage used as input
    - `state` 'STARTING' | 'ACTIVE' | 'STOPPING' | 'FAILED' | 'STOPPED', required — State of the Composition.
    - `layout` object, required — Layout object to configure composition parameters.
      - `grid` object — Configuration related to grid layout. Default: Grid layout.
        - `featuredParticipantAttribute` string — This attribute name identifies the featured slot. A participant with this attribute set to <code>"true"</code> (as a string value) in <a>ParticipantTokenConfiguration</a> is placed in the featured slot. Default: <code>""</code> (no featured participant).
        - `omitStoppedVideo` boolean — Determines whether to omit participants with stopped video in the composition. Default: <code>false</code>.
        - `videoAspectRatio` 'AUTO' | 'VIDEO' | 'SQUARE' | 'PORTRAIT' — Sets the non-featured participant display mode, to control the aspect ratio of video tiles. <code>VIDEO</code> is 16:9, <code>SQUARE</code> is 1:1, and <code>PORTRAIT</code> is 3:4. Default: <code>VIDEO</code>.
        - `videoFillMode` 'FILL' | 'COVER' | 'CONTAIN' — Defines how video content fits within the participant tile: <code>FILL</code> (stretched), <code>COVER</code> (cropped), or <code>CONTAIN</code> (letterboxed). When not set, <code>videoFillMode</code> defaults to <code>COVER</code> fill mode for participants in the grid and to <code>CONTAIN</code> fill mode for featured participants.
        - `gridGap` integer — Specifies the spacing between participant tiles in pixels. Default: <code>2</code>.
        - `participantOrderAttribute` string — Attribute name in <a>ParticipantTokenConfiguration</a> identifying the participant ordering key. Participants with <code>participantOrderAttribute</code> set to <code>""</code> or not specified are ordered based on their arrival time into the stage.
      - `pip` object — Configuration related to PiP layout.
        - `featuredParticipantAttribute` string — This attribute name identifies the featured slot. A participant with this attribute set to <code>"true"</code> (as a string value) in <a>ParticipantTokenConfiguration</a> is placed in the featured slot. Default: <code>""</code> (no featured participant).
        - `omitStoppedVideo` boolean — Determines whether to omit participants with stopped video in the composition. Default: <code>false</code>.
        - `videoFillMode` 'FILL' | 'COVER' | 'CONTAIN' — Defines how video content fits within the participant tile: <code>FILL</code> (stretched), <code>COVER</code> (cropped), or <code>CONTAIN</code> (letterboxed). Default: <code>COVER</code>.
        - `gridGap` integer — Specifies the spacing between participant tiles in pixels. Default: <code>0</code>.
        - `pipParticipantAttribute` string — Specifies the participant for the PiP window. A participant with this attribute set to <code>"true"</code> (as a string value) in <a>ParticipantTokenConfiguration</a> is placed in the PiP slot. Default: <code>""</code> (no PiP participant).
        - `pipBehavior` 'STATIC' | 'DYNAMIC' — Defines PiP behavior when all participants have left: <code>STATIC</code> (maintains original position/size) or <code>DYNAMIC</code> (expands to full composition). Default: <code>STATIC</code>.
        - `pipOffset` integer — Sets the PiP window’s offset position in pixels from the closest edges determined by <code>PipPosition</code>. Default: <code>0</code>.
        - `pipPosition` 'TOP_LEFT' | 'TOP_RIGHT' | 'BOTTOM_LEFT' | 'BOTTOM_RIGHT' — Determines the corner position of the PiP window. Default: <code>BOTTOM_RIGHT</code>.
        - `pipWidth` integer — Specifies the width of the PiP window in pixels. When this is not set explicitly, <code>pipWidth</code>’s value will be based on the size of the composition and the aspect ratio of the participant’s video.
        - `pipHeight` integer — Specifies the height of the PiP window in pixels. When this is not set explicitly, <code>pipHeight</code>’s value will be based on the size of the composition and the aspect ratio of the participant’s video.
        - `participantOrderAttribute` string — Attribute name in <a>ParticipantTokenConfiguration</a> identifying the participant ordering key. Participants with <code>participantOrderAttribute</code> set to <code>""</code> or not specified are ordered based on their arrival time into the stage.
    - `destinations` Destination[], required — Array of Destination objects. A Composition can contain either one destination (<code>channel</code> or <code>s3</code>) or two (one <code>channel</code> and one <code>s3</code>).
      - `id` string, required — Unique identifier for this destination, assigned by IVS.
      - `state` 'STARTING' | 'ACTIVE' | 'STOPPING' | 'RECONNECTING' | 'FAILED' | 'STOPPED', required — State of the Composition Destination.
      - `startTime` string, date-time — UTC time of the destination start. This is an ISO 8601 timestamp; <i>note that this is returned as a string</i>.
      - `endTime` string, date-time — UTC time of the destination end. This is an ISO 8601 timestamp; <i>note that this is returned as a string</i>.
      - `configuration` object, required — Configuration used to create this destination.
        - `name` string — Name that can be specified to help identify the destination.
        - `channel` object — An IVS channel to be used for broadcasting, for server-side composition. Either a <code>channel</code> or an <code>s3</code> must be specified.
          - `channelArn` string, required — ARN of the channel to use for broadcasting. The channel and stage resources must be in the same AWS account and region. The channel must be offline (not broadcasting).
          - `encoderConfigurationArn` string — ARN of the <a>EncoderConfiguration</a> resource. The encoder configuration and stage resources must be in the same AWS account and region.
        - `s3` object — An S3 storage configuration to be used for recording video data. Either a <code>channel</code> or an <code>s3</code> must be specified.
          - `storageConfigurationArn` string, required — ARN of the <a>StorageConfiguration</a> where recorded videos will be stored.
          - `encoderConfigurationArns` EncoderConfigurationArn[], required — ARNs of the <a>EncoderConfiguration</a> resource. The encoder configuration and stage resources must be in the same AWS account and region.
          - `recordingConfiguration` object — Array of maps, each of the form <code>string:string (key:value)</code>. This is an optional customer specification, currently used only to specify the recording format for storing a recording in Amazon S3.
            - `hlsConfiguration` object — An HLS configuration object to return information about how the recording will be configured.
              - …
            - `format` 'HLS' — The recording format for storing a recording in Amazon S3.
          - `thumbnailConfigurations` CompositionThumbnailConfiguration[] — A complex type that allows you to enable/disable the recording of thumbnails for a <a>Composition</a> and modify the interval at which thumbnails are generated for the live session.
            - `targetIntervalSeconds` integer — The targeted thumbnail-generation interval in seconds. Default: 60.
            - `storage` ThumbnailStorageType[] — Indicates the format in which thumbnails are recorded. <code>SEQUENTIAL</code> records all generated thumbnails in a serial manner, to the media/thumbnails/(width)x(height) directory, where (width) and (height) are the width and height of the thumbnail. <code>LATEST</code> saves the latest thumbnail in media/latest_thumbnail/(width)x(height)/thumb.jpg and overwrites it at the interval specified by <code>targetIntervalSeconds</code>. You can enable both <code>SEQUENTIAL</code> and <code>LATEST</code>. Default: <code>SEQUENTIAL</code>.
      - `detail` object — Optional details regarding the status of the destination.
        - `s3` object — An S3 detail object to return information about the S3 destination.
          - `recordingPrefix` string, required — The S3 bucket prefix under which the recording is stored.
    - `tags` object — Tags attached to the resource. Array of maps, each of the form <code>string:string (key:value)</code>. See <a href="https://docs.aws.amazon.com/tag-editor/latest/userguide/best-practices-and-strats.html">Best practices and strategies</a> in <i>Tagging AWS Resources and Tag Editor</i> for details, including restrictions that apply to tags and "Tag naming limits and requirements"; Amazon IVS has no constraints on tags beyond what is documented there.
    - `startTime` string, date-time — UTC time of the Composition start. This is an ISO 8601 timestamp; <i>note that this is returned as a string</i>.
    - `endTime` string, date-time — UTC time of the Composition end. This is an ISO 8601 timestamp; <i>note that this is returned as a string</i>.

## Other responses

- `480` — ResourceNotFoundException
- `481` — ValidationException
- `482` — AccessDeniedException
- `483` — InternalServerException
- `484` — ServiceQuotaExceededException
- `485` — ConflictException

---

[API](https://skmtc.net/aws/apis/ivs-realtime.md) · [All operations](https://skmtc.net/aws/apis/ivs-realtime/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/aws/ivs-realtime/versions/f8857274a50f/schema)