Amazon Clean Rooms Protected Queries API

Operations for executing and managing protected queries

GitHub OpenAPI

Operations 4

GET /memberships/{membershipIdentifier}/protectedQueries/{protectedQueryIdentifier} Get Protected Query #
PATCH /memberships/{membershipIdentifier}/protectedQueries/{protectedQueryIdentifier} Update Protected Query #
GET /memberships/{membershipIdentifier}/protectedQueries List Protected Queries #
POST /memberships/{membershipIdentifier}/protectedQueries Start Protected Query #

Documentation

Specifications

Examples

Schemas & Data

Other Resources

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/amazon-clean-rooms:amazon-clean-rooms-protected-queries-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

amazon-clean-rooms-protected-queries-api-openapi.yml Raw ↑
openapi: 3.1.0
info:
  title: AWS Clean Rooms Service Protected Queries API
  version: '2022-02-17'
  description: Generated from AWS's published Smithy model for AWS Clean Rooms Service. 4 operation(s).
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/contact-us/
  license:
    name: Apache 2.0
    identifier: Apache-2.0
    url: https://github.com/aws/api-models-aws/blob/main/LICENSE
servers:
- url: https://cleanrooms.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
paths:
  /memberships/{membershipIdentifier}/protectedQueries/{protectedQueryIdentifier}:
    get:
      operationId: GetProtectedQuery
      summary: Get Protected Query
      description: Returns query processing metadata.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetProtectedQueryOutput'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetProtectedQueryInput'
      tags:
      - Protected Queries
    patch:
      operationId: UpdateProtectedQuery
      summary: Update Protected Query
      description: Updates the processing of a currently running query.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateProtectedQueryOutput'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '409':
          description: ConflictException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProtectedQueryInput'
      tags:
      - Protected Queries
  /memberships/{membershipIdentifier}/protectedQueries:
    get:
      operationId: ListProtectedQueries
      summary: List Protected Queries
      description: Lists protected queries, sorted by the most recent query.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListProtectedQueriesOutput'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListProtectedQueriesInput'
      tags:
      - Protected Queries
    post:
      operationId: StartProtectedQuery
      summary: Start Protected Query
      description: Creates a protected query that is started by Clean Rooms.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartProtectedQueryOutput'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '402':
          description: ServiceQuotaExceededException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceQuotaExceededException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartProtectedQueryInput'
      tags:
      - Protected Queries
components:
  securitySchemes:
    sigv4:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4. The Authorization header carries an AWS4-HMAC-SHA256 signature over the canonical
        request, with X-Amz-Date (and X-Amz-Security-Token for temporary credentials). Not a bearer token.
      x-aws-sigv4:
        signingName: cleanrooms
  schemas:
    AccessDeniedException:
      type: object
      properties:
        message:
          type: string
        reason:
          type: string
          description: A reason code for the exception.
    BilledResourceUtilization:
      type: object
      properties:
        units:
          type: number
          description: The number of Clean Rooms Processing Unit (CRPU) hours that have been billed.
      required:
      - units
    ComputeConfiguration:
      type: object
      properties:
        worker:
          $ref: '#/components/schemas/WorkerComputeConfiguration'
      description: Exactly one member is set.
    ConfigurationDetails:
      type: object
      properties:
        directAnalysisConfigurationDetails:
          $ref: '#/components/schemas/DirectAnalysisConfigurationDetails'
      description: Exactly one member is set.
    ConflictException:
      type: object
      properties:
        message:
          type: string
        resourceId:
          type: string
          description: The ID of the conflicting resource.
        resourceType:
          type: string
          description: The type of the conflicting resource.
        reason:
          type: string
          description: A reason code for the exception.
    DifferentialPrivacyParameters:
      type: object
      properties:
        sensitivityParameters:
          type: array
          items:
            $ref: '#/components/schemas/DifferentialPrivacySensitivityParameters'
          description: Provides the sensitivity parameters that you can use to better understand the total amount of noise
            in query results.
      required:
      - sensitivityParameters
    DifferentialPrivacySensitivityParameters:
      type: object
      properties:
        aggregationType:
          type: string
          enum:
          - AVG
          - COUNT
          - COUNT_DISTINCT
          - SUM
          - STDDEV
          description: The type of aggregation function that was run.
        aggregationExpression:
          type: string
          description: The aggregation expression that was run.
        userContributionLimit:
          type: integer
          description: The maximum number of rows contributed by a user in a SQL query.
        minColumnValue:
          type: number
          description: The lower bound of the aggregation expression.
        maxColumnValue:
          type: number
          description: The upper bound of the aggregation expression.
      required:
      - aggregationType
      - aggregationExpression
      - userContributionLimit
    DirectAnalysisConfigurationDetails:
      type: object
      properties:
        receiverAccountIds:
          type: array
          items:
            type: string
          description: The account IDs for the member who received the results of a protected query.
    GetProtectedQueryInput:
      type: object
      properties:
        membershipIdentifier:
          type: string
          description: The identifier for a membership in a protected query instance.
        protectedQueryIdentifier:
          type: string
          description: The identifier for a protected query instance.
      required:
      - membershipIdentifier
      - protectedQueryIdentifier
    GetProtectedQueryOutput:
      type: object
      properties:
        protectedQuery:
          $ref: '#/components/schemas/ProtectedQuery'
      required:
      - protectedQuery
    IntermediateTableOutputConfiguration:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the intermediate table.
        arn:
          type: string
          description: The Amazon Resource Name (ARN) of the intermediate table.
        name:
          type: string
          description: The name of the intermediate table.
      required:
      - id
      - arn
      - name
    InternalServerException:
      type: object
      properties:
        message:
          type: string
    ListProtectedQueriesInput:
      type: object
      properties:
        membershipIdentifier:
          type: string
          description: The identifier for the membership in the collaboration.
        status:
          type: string
          description: A filter on the status of the protected query.
        nextToken:
          type: string
          description: The pagination token that's used to fetch the next set of results.
        maxResults:
          type: integer
          description: The maximum number of results that are returned for an API request call. The service chooses a default
            number if you don't set one. The service might return a `nextToken` even if the `maxResults` value has not been
            met.
      required:
      - membershipIdentifier
    ListProtectedQueriesOutput:
      type: object
      properties:
        nextToken:
          type: string
          description: The pagination token that's used to fetch the next set of results.
        protectedQueries:
          type: array
          items:
            $ref: '#/components/schemas/ProtectedQuerySummary'
          description: A list of protected queries.
      required:
      - protectedQueries
    ProtectedQuery:
      type: object
      properties:
        id:
          type: string
          description: The identifier for a protected query instance.
        membershipId:
          type: string
          description: The identifier for the membership.
        membershipArn:
          type: string
          description: The ARN of the membership.
        createTime:
          type: string
          description: The time at which the protected query was created.
        sqlParameters:
          $ref: '#/components/schemas/ProtectedQuerySQLParameters'
        status:
          type: string
          description: The status of the query.
        resultConfiguration:
          $ref: '#/components/schemas/ProtectedQueryResultConfiguration'
        statistics:
          $ref: '#/components/schemas/ProtectedQueryStatistics'
        result:
          $ref: '#/components/schemas/ProtectedQueryResult'
        error:
          $ref: '#/components/schemas/ProtectedQueryError'
        differentialPrivacy:
          $ref: '#/components/schemas/DifferentialPrivacyParameters'
        computeConfiguration:
          $ref: '#/components/schemas/ComputeConfiguration'
        queryComputePayerAccountId:
          type: string
          description: The account ID of the member that pays for the query compute costs.
      required:
      - id
      - membershipId
      - membershipArn
      - createTime
      - status
    ProtectedQueryDistributeOutput:
      type: object
      properties:
        s3:
          $ref: '#/components/schemas/ProtectedQueryS3Output'
        memberList:
          type: array
          items:
            $ref: '#/components/schemas/ProtectedQuerySingleMemberOutput'
          description: Contains the output results for each member location specified in the distribute output configuration.
            Each entry provides details about the result distribution to a specific collaboration member.
    ProtectedQueryDistributeOutputConfiguration:
      type: object
      properties:
        locations:
          type: array
          items:
            $ref: '#/components/schemas/ProtectedQueryDistributeOutputConfigurationLocation'
          description: A list of locations where you want to distribute the protected query results. Each location must specify
            either an S3 destination or a collaboration member destination. You can't specify more than one S3 location. You
            can't specify the query runner's account as a member location. You must include either an S3 or member output
            configuration for each location, but not both.
      required:
      - locations
    ProtectedQueryDistributeOutputConfigurationLocation:
      type: object
      properties:
        s3:
          $ref: '#/components/schemas/ProtectedQueryS3OutputConfiguration'
        member:
          $ref: '#/components/schemas/ProtectedQueryMemberOutputConfiguration'
      description: Exactly one member is set.
    ProtectedQueryError:
      type: object
      properties:
        message:
          type: string
          description: A description of why the query failed.
        code:
          type: string
          description: An error code for the error.
      required:
      - message
      - code
    ProtectedQueryMemberOutputConfiguration:
      type: object
      properties:
        accountId:
          type: string
          description: The unique identifier for the account.
      required:
      - accountId
    ProtectedQueryOutput:
      type: object
      properties:
        s3:
          $ref: '#/components/schemas/ProtectedQueryS3Output'
        memberList:
          type: array
          items:
            $ref: '#/components/schemas/ProtectedQuerySingleMemberOutput'
          description: The list of member Amazon Web Services account(s) that received the results of the query.
        distribute:
          $ref: '#/components/schemas/ProtectedQueryDistributeOutput'
      description: Exactly one member is set.
    ProtectedQueryOutputConfiguration:
      type: object
      properties:
        s3:
          $ref: '#/components/schemas/ProtectedQueryS3OutputConfiguration'
        member:
          $ref: '#/components/schemas/ProtectedQueryMemberOutputConfiguration'
        distribute:
          $ref: '#/components/schemas/ProtectedQueryDistributeOutputConfiguration'
        intermediateTable:
          $ref: '#/components/schemas/IntermediateTableOutputConfiguration'
      description: Exactly one member is set.
    ProtectedQueryResult:
      type: object
      properties:
        output:
          $ref: '#/components/schemas/ProtectedQueryOutput'
      required:
      - output
    ProtectedQueryResultConfiguration:
      type: object
      properties:
        outputConfiguration:
          $ref: '#/components/schemas/ProtectedQueryOutputConfiguration'
      required:
      - outputConfiguration
    ProtectedQueryS3Output:
      type: object
      properties:
        location:
          type: string
          description: The S3 location of the result.
      required:
      - location
    ProtectedQueryS3OutputConfiguration:
      type: object
      properties:
        resultFormat:
          type: string
          enum:
          - CSV
          - PARQUET
          description: Intended file format of the result.
        bucket:
          type: string
          description: The S3 bucket to unload the protected query results.
        keyPrefix:
          type: string
          description: The S3 prefix to unload the protected query results.
        singleFileOutput:
          type: boolean
          description: Indicates whether files should be output as a single file (TRUE) or output as multiple files (FALSE).
            This parameter is only supported for analyses with the Spark analytics engine.
      required:
      - resultFormat
      - bucket
    ProtectedQuerySQLParameters:
      type: object
      properties:
        queryString:
          type: string
          description: The query string to be submitted.
        analysisTemplateArn:
          type: string
          description: The Amazon Resource Name (ARN) associated with the analysis template within a collaboration.
        parameters:
          type: object
          additionalProperties:
            type: string
          description: The protected query SQL parameters.
    ProtectedQuerySingleMemberOutput:
      type: object
      properties:
        accountId:
          type: string
          description: The Amazon Web Services account ID of the member in the collaboration who can receive results for the
            query.
      required:
      - accountId
    ProtectedQueryStatistics:
      type: object
      properties:
        totalDurationInMillis:
          type: integer
          description: The duration of the protected query, from creation until query completion, in milliseconds.
        billedResourceUtilization:
          $ref: '#/components/schemas/BilledResourceUtilization'
    ProtectedQuerySummary:
      type: object
      properties:
        id:
          type: string
          description: The unique ID of the protected query.
        membershipId:
          type: string
          description: The unique ID for the membership that initiated the protected query.
        membershipArn:
          type: string
          description: The unique ARN for the membership that initiated the protected query.
        createTime:
          type: string
          description: The time the protected query was created.
        status:
          type: string
          description: The status of the protected query.
        receiverConfigurations:
          type: array
          items:
            $ref: '#/components/schemas/ReceiverConfiguration'
          description: The receiver configuration.
        queryComputePayerAccountId:
          type: string
          description: The account ID of the member that pays for the query compute costs.
        intermediateTableConfiguration:
          $ref: '#/components/schemas/IntermediateTableOutputConfiguration'
      required:
      - id
      - membershipId
      - membershipArn
      - createTime
      - status
      - receiverConfigurations
    ReceiverConfiguration:
      type: object
      properties:
        analysisType:
          type: string
          enum:
          - DIRECT_ANALYSIS
          - ADDITIONAL_ANALYSIS
          description: The type of analysis for the protected query. The results of the query can be analyzed directly (DIRECT_ANALYSIS)
            or used as input into additional analyses (ADDITIONAL_ANALYSIS), such as a query that is a seed for a lookalike
            ML model.
        configurationDetails:
          $ref: '#/components/schemas/ConfigurationDetails'
      required:
      - analysisType
    ResourceNotFoundException:
      type: object
      properties:
        message:
          type: string
        resourceId:
          type: string
          description: The Id of the missing resource.
        resourceType:
          type: string
          description: The type of the missing resource.
      required:
      - message
      - resourceId
      - resourceType
    ServiceQuotaExceededException:
      type: object
      properties:
        message:
          type: string
        quotaName:
          type: string
          description: The name of the quota.
        quotaValue:
          type: number
          description: The value of the quota.
      required:
      - message
      - quotaName
      - quotaValue
    StartProtectedQueryInput:
      type: object
      properties:
        type:
          type: string
          description: The type of the protected query to be started.
        membershipIdentifier:
          type: string
          description: A unique identifier for the membership to run this query against. Currently accepts a membership ID.
        sqlParameters:
          $ref: '#/components/schemas/ProtectedQuerySQLParameters'
        resultConfiguration:
          $ref: '#/components/schemas/ProtectedQueryResultConfiguration'
        computeConfiguration:
          $ref: '#/components/schemas/ComputeConfiguration'
        queryComputePayerAccountId:
          type: string
          description: The account ID of the member that pays for the query compute costs.
      required:
      - type
      - membershipIdentifier
      - sqlParameters
    StartProtectedQueryOutput:
      type: object
      properties:
        protectedQuery:
          $ref: '#/components/schemas/ProtectedQuery'
      required:
      - protectedQuery
    ThrottlingException:
      type: object
      properties:
        message:
          type: string
    UpdateProtectedQueryInput:
      type: object
      properties:
        membershipIdentifier:
          type: string
          description: The identifier for a member of a protected query instance.
        protectedQueryIdentifier:
          type: string
          description: The identifier for a protected query instance.
        targetStatus:
          type: string
          description: The target status of a query. Used to update the execution status of a currently running query.
      required:
      - membershipIdentifier
      - protectedQueryIdentifier
      - targetStatus
    UpdateProtectedQueryOutput:
      type: object
      properties:
        protectedQuery:
          $ref: '#/components/schemas/ProtectedQuery'
      required:
      - protectedQuery
    ValidationException:
      type: object
      properties:
        message:
          type: string
        reason:
          type: string
          description: A reason code for the exception.
        fieldList:
          type: array
          items:
            $ref: '#/components/schemas/ValidationExceptionField'
          description: Validation errors for specific input parameters.
    ValidationExceptionField:
      type: object
      properties:
        name:
          type: string
          description: The name of the input parameter.
        message:
          type: string
          description: A message for the input validation error.
      required:
      - name
      - message
    WorkerComputeConfiguration:
      type: object
      properties:
        type:
          type: string
          enum:
          - CR.1X
          - CR.4X
          - CR.8X
          description: The worker compute configuration type.
        number:
          type: integer
          description: The number of workers. SQL queries support a minimum value of 2 and a maximum value of 400. PySpark
            jobs support a minimum value of 4 and a maximum value of 128.
        properties:
          $ref: '#/components/schemas/WorkerComputeConfigurationProperties'
    WorkerComputeConfigurationProperties:
      type: object
      properties:
        spark:
          type: object
          additionalProperties:
            type: string
          description: The Spark configuration properties for SQL and PySpark workloads. This map contains key-value pairs
            that configure Apache Spark settings to optimize performance for your data processing jobs. You can specify up
            to 50 Spark properties, with each key being 1-200 characters and each value being 0-500 characters. These properties
            allow you to adjust compute capacity for large datasets and complex workloads.
      description: Exactly one member is set.
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/3cd98287b471c106254abd89279cc87308d38bfd/models/cleanrooms/service/2022-02-17/cleanrooms-2022-02-17.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)