Amazon Redshift Statement Execution API

openapi: 3.1.0
info:
  title: Amazon Redshift Data Metadata Statement Execution API
  description: The Amazon Redshift Data API enables you to run SQL statements on Amazon Redshift clusters and Amazon Redshift Serverless workgroups without managing database connections or drivers. The Data API handles connection management, authentication via IAM or Secrets Manager, and supports asynchronous execution of SQL statements with result retrieval through a statement identifier. Ideal for building serverless applications, integrating with AWS Lambda, and running ad-hoc queries programmatically.
  version: '2019-12-20'
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/redshift/
  termsOfService: https://aws.amazon.com/service-terms/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://redshift-data.{region}.amazonaws.com
  description: Amazon Redshift Data API regional endpoint
  variables:
    region:
      default: us-east-1
      description: AWS region identifier
      enum:
      - us-east-1
      - us-east-2
      - us-west-1
      - us-west-2
      - eu-west-1
      - eu-west-2
      - eu-central-1
      - ap-southeast-1
      - ap-southeast-2
      - ap-northeast-1
      - ap-northeast-2
      - ca-central-1
      - sa-east-1
security:
- sigv4Auth: []
tags:
- name: Statement Execution
  description: Execute SQL statements against Amazon Redshift clusters or serverless workgroups
paths:
  /ExecuteStatement:
    post:
      operationId: executeStatement
      summary: Amazon Redshift Execute a Sql Statement
      description: Runs a SQL statement against an Amazon Redshift cluster or Amazon Redshift Serverless workgroup. The SQL statement runs asynchronously and returns a statement identifier that you can use to check the status with DescribeStatement and retrieve results with GetStatementResult. The maximum query result size is 100 MB.
      tags:
      - Statement Execution
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecuteStatementRequest'
      responses:
        '200':
          description: Statement submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecuteStatementResponse'
        '400':
          description: Invalid request - validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '503':
          description: Service temporarily unavailable - the cluster is paused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActiveStatementsExceededException'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /BatchExecuteStatement:
    post:
      operationId: batchExecuteStatement
      summary: Amazon Redshift Execute Multiple Sql Statements in a Batch
      description: Runs one or more SQL statements as a batch, which run as a single transaction. The statements run serially in the order provided. Returns a statement identifier for the batch that you can use with DescribeStatement and GetStatementResult.
      tags:
      - Statement Execution
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchExecuteStatementRequest'
      responses:
        '200':
          description: Batch statement submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchExecuteStatementResponse'
        '400':
          description: Invalid request - validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    SqlParameter:
      type: object
      required:
      - name
      - value
      properties:
        name:
          type: string
          description: The name of the parameter (without the colon prefix)
          example: sale_date
        value:
          type: string
          description: The value of the parameter
          example: '2025-01-01'
    ActiveStatementsExceededException:
      type: object
      properties:
        Message:
          type: string
          description: A description indicating the maximum number of active statements has been exceeded
          example: example_value
    ExecuteStatementRequest:
      type: object
      required:
      - Database
      - Sql
      properties:
        ClusterIdentifier:
          type: string
          description: The cluster identifier. Required when connecting to a provisioned cluster. Mutually exclusive with WorkgroupName.
          example: my-redshift-cluster
        Database:
          type: string
          description: The name of the database to run the SQL statement against
          example: dev
        DbUser:
          type: string
          description: The database user name. Required when authenticating with temporary credentials from GetClusterCredentials.
          example: example_value
        SecretArn:
          type: string
          description: The ARN of the secret stored in AWS Secrets Manager that contains the database credentials. Mutually exclusive with DbUser and temporary credentials.
          example: arn:aws:secretsmanager:us-east-1:123456789012:secret:my-redshift-secret-AbCdEf
        Sql:
          type: string
          description: The SQL statement to run. Maximum length is 100,000 characters.
          maxLength: 100000
          example: SELECT * FROM sales ORDER BY sale_date DESC LIMIT 10
        StatementName:
          type: string
          description: A name for the SQL statement. This name can be used to identify the query in the ListStatements output.
          example: my-sales-query
        WithEvent:
          type: boolean
          description: Whether to send an event to Amazon EventBridge when the SQL statement completes. Default is false.
          default: false
          example: true
        WorkgroupName:
          type: string
          description: The serverless workgroup name. Required when connecting to Redshift Serverless. Mutually exclusive with ClusterIdentifier.
          example: my-workgroup
        Parameters:
          type: array
          description: Named parameters for the SQL statement. Use :name syntax in the SQL string to reference parameters.
          items:
            $ref: '#/components/schemas/SqlParameter'
          example: []
        ClientToken:
          type: string
          description: A unique, case-sensitive identifier to ensure idempotency of the request.
          example: example_value
    BatchExecuteStatementResponse:
      type: object
      properties:
        Id:
          type: string
          format: uuid
          description: The identifier of the batch SQL statement
          example: abc123
        CreatedAt:
          type: string
          format: date-time
          description: The date and time the batch statement was created
          example: '2026-01-15T10:30:00Z'
        Database:
          type: string
          description: The name of the database
          example: example_value
        DbUser:
          type: string
          description: The database user
          example: example_value
        ClusterIdentifier:
          type: string
          description: The cluster identifier
          example: example_value
        WorkgroupName:
          type: string
          description: The serverless workgroup name
          example: example_value
        SecretArn:
          type: string
          description: The secret ARN used for authentication
          example: example_value
    ValidationException:
      type: object
      properties:
        Message:
          type: string
          description: A description of the validation error
          example: example_value
    BatchExecuteStatementRequest:
      type: object
      required:
      - Database
      - Sqls
      properties:
        ClusterIdentifier:
          type: string
          description: The cluster identifier for a provisioned cluster
          example: example_value
        Database:
          type: string
          description: The name of the database
          example: example_value
        DbUser:
          type: string
          description: The database user name for temporary credentials
          example: example_value
        SecretArn:
          type: string
          description: ARN of the secret in AWS Secrets Manager
          example: example_value
        Sqls:
          type: array
          description: One or more SQL statements to run. The statements run serially as a single transaction. Maximum 40 statements.
          items:
            type: string
          minItems: 1
          maxItems: 40
          example: []
        StatementName:
          type: string
          description: A name for the batch SQL statement
          example: example_value
        WithEvent:
          type: boolean
          description: Whether to send an event to EventBridge on completion
          default: false
          example: true
        WorkgroupName:
          type: string
          description: The serverless workgroup name
          example: example_value
        ClientToken:
          type: string
          description: Idempotency token
          example: example_value
    ExecuteStatementResponse:
      type: object
      properties:
        Id:
          type: string
          format: uuid
          description: The identifier of the SQL statement
          example: abc123
        CreatedAt:
          type: string
          format: date-time
          description: The date and time the statement was created
          example: '2026-01-15T10:30:00Z'
        Database:
          type: string
          description: The name of the database
          example: example_value
        DbUser:
          type: string
          description: The database user
          example: example_value
        ClusterIdentifier:
          type: string
          description: The cluster identifier
          example: example_value
        WorkgroupName:
          type: string
          description: The serverless workgroup name
          example: example_value
        SecretArn:
          type: string
          description: The secret ARN used for authentication
          example: example_value
    InternalServerException:
      type: object
      properties:
        Message:
          type: string
          description: A description of the internal server error
          example: example_value
  securitySchemes:
    sigv4Auth:
      type: apiKey
      name: Authorization
      in: header
      description: AWS Signature Version 4 authentication. Requests are signed using IAM credentials. The Data API also supports authentication via AWS Secrets Manager for database credentials or temporary IAM credentials.
externalDocs:
  description: Amazon Redshift Data API Reference
  url: https://docs.aws.amazon.com/redshift-data/latest/APIReference/Welcome.html