Iterable Experiments API

openapi: 3.2.0
info:
  title: Iterable Experiments API
  version: '1.0'
  description: 'Operations tagged experiments across 2 of this provider''s published API definitions: iterable-api-openapi.json, iterable-rest-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.iterable.com/
- url: https://api.iterable.com/api
  description: US Data Center (USDC)
- url: https://api.eu.iterable.com/api
  description: European Data Center (EDC)
tags:
- name: Experiments
paths:
  /api/experiments/metrics:
    get:
      description: Get metrics for a single experiment or for multiple experiments. Note that we currently only support exporting email experiment metrics.
      operationId: metrics
      parameters:
      - description: Experiment to export. Specify multiple experimentId query parameters to export multiple experiments.
        in: query
        name: experimentId
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: object
      - description: Campaign whose experiments you want to export. Specify multiple campaignId query parameters to export multiple campaigns.
        in: query
        name: campaignId
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: object
      - description: export starting from (>=)
        in: query
        name: startDateTime
        required: false
        schema:
          type: string
          format: date-time
          default: '2018-06-25'
      - description: export ending at (<=)
        in: query
        name: endDateTime
        required: false
        schema:
          type: string
          format: date-time
          default: '2018-07-25'
      responses:
        '200':
          description: successful operation
          content:
            text/csv:
              schema:
                $ref: '#/components/schemas/ExperimentMetricsResponse'
        '400':
          description: Invalid parameters
        '401':
          description: Invalid API key
      summary: Get metrics for experiments
      tags:
      - Experiments
      security:
      - api_key: []
    servers:
    - url: https://api.iterable.com/
  /api/experiments:
    get:
      description: Get a list of experiments with optional filtering by campaign, state, and date range.
      operationId: list
      parameters:
      - description: Filter by campaign ID
        in: query
        name: campaignId
        required: false
        schema:
          type: integer
          format: int64
      - description: 'Filter by experiment state. Valid values: draft, ready, running, finished, winner_found'
        in: query
        name: state
        required: false
        schema:
          type: string
          enum:
          - draft
          - ready
          - running
          - finished
          - winner_found
      - description: Filter by start date (>=)
        in: query
        name: startDateTime
        required: false
        schema:
          type: string
          format: date-time
      - description: Filter by end date (<=)
        in: query
        name: endDateTime
        required: false
        schema:
          type: string
          format: date-time
      - description: 'Maximum number of results to return (default: 20, max: 100)'
        in: query
        name: limit
        required: false
        schema:
          type: integer
          format: int32
          default: 20
      - description: 'Number of results to skip (default: 0)'
        in: query
        name: offset
        required: false
        schema:
          type: integer
          format: int32
          default: 0
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExperimentListResponse'
        '400':
          description: Invalid parameters
        '401':
          description: Invalid API key
      summary: List experiments
      tags:
      - Experiments
      security:
      - api_key: []
    servers:
    - url: https://api.iterable.com/
  /api/experiments/{experimentId}:
    get:
      description: Get a single experiment by ID.
      operationId: get
      parameters:
      - description: Experiment ID
        in: path
        name: experimentId
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExperimentResponse'
        '400':
          description: Invalid parameters
        '401':
          description: Invalid API key
        '404':
          description: Experiment not found
      summary: Get experiment
      tags:
      - Experiments
      security:
      - api_key: []
    servers:
    - url: https://api.iterable.com/
  /api/experiments/{experimentId}/variants:
    get:
      description: Get all variants for an experiment.
      operationId: variants
      parameters:
      - description: Experiment ID
        in: path
        name: experimentId
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExperimentVariantsResponse'
        '400':
          description: Invalid parameters
        '401':
          description: Invalid API key
        '404':
          description: Experiment not found
      summary: Get experiment variants
      tags:
      - Experiments
      security:
      - api_key: []
    servers:
    - url: https://api.iterable.com/
  /experiments/metrics:
    get:
      operationId: getExperimentMetrics
      summary: Get experiment metrics
      description: Retrieves experiment metrics for A/B tests. Supports multiple experiment IDs and campaign IDs as query parameters, up to 200 total.
      tags:
      - Experiments
      parameters:
      - name: experimentId
        in: query
        description: One or more experiment IDs
        schema:
          type: array
          items:
            type: integer
      - name: campaignId
        in: query
        description: One or more campaign IDs
        schema:
          type: array
          items:
            type: integer
      responses:
        '200':
          description: Experiment metrics as CSV
          content:
            text/csv:
              schema:
                type: string
        '401':
          description: Unauthorized
      security:
      - apiKeyAuth: []
    servers:
    - url: https://api.iterable.com/api
      description: US Data Center (USDC)
    - url: https://api.eu.iterable.com/api
      description: European Data Center (EDC)
components:
  schemas:
    ExperimentVariantValue:
      description: Typed variant value payload. Only present fields are serialized.
      properties:
        sendTime:
          description: Send time for send-time variants (ISO-8601 string)
          type: string
        stoGroup:
          description: STO group identifier for STO variants
          type: string
        templateId:
          description: Template ID for template-based variants
          format: int64
          type: integer
      type: object
    ExperimentVariantsResponse:
      description: Response for experiment variants with content
      properties:
        experimentId:
          description: Experiment ID
          format: int64
          type: integer
        variants:
          description: List of variants with content
          items:
            $ref: '#/components/schemas/VariantContentResponse'
          type: array
      required:
      - experimentId
      - variants
      type: object
    VariantContentResponse:
      description: Variant with content details
      properties:
        content:
          $ref: '#/components/schemas/TemplateContentResponse'
          description: Template content
        currentPercentage:
          description: Percentage of total audience distributed to this variant, allocated based on the type of experiment you're running.
          format: double
          type: number
        name:
          description: Variant name
          type: string
        value:
          $ref: '#/components/schemas/ExperimentVariantValue'
          description: Typed variant value object (e.g., templateId/sendTime/stoGroup)
        variantId:
          description: Variant ID
          format: int64
          type: integer
      required:
      - currentPercentage
      - name
      - value
      - variantId
      type: object
    TemplateContentResponse:
      description: Template content for a variant
      properties:
        htmlSource:
          description: HTML source of the template
          type: string
        plainText:
          description: Plain text version of the template
          type: string
        preheader:
          description: Email preheader text
          type: string
        subject:
          description: Email subject line
          type: string
      type: object
    ExperimentResponse:
      description: Full experiment details
      properties:
        allocationMode:
          description: Traffic allocation mode
          type: string
        channelType:
          description: Channel type for the experiment.
          type: string
          enum:
          - email
          - push
          - sms
          - in_app
          - web_push
        constraints:
          $ref: '#/components/schemas/ExperimentConstraints'
          description: Experiment constraints/targeting
        creationDate:
          description: Date the experiment was created
          format: date-time
          type: string
        experimentType:
          description: Experiment type
          type: string
        finishDate:
          description: End date of the experiment
          format: date-time
          type: string
        id:
          description: Experiment ID
          format: int64
          type: integer
        meta:
          $ref: '#/components/schemas/ExperimentMeta'
          description: Experiment metadata
        sizing:
          $ref: '#/components/schemas/ExperimentSizingResponse'
          description: Traffic allocation sizing details
        startDate:
          description: Start date of the experiment
          format: date-time
          type: string
        status:
          description: Experiment status
          type: string
          enum:
          - draft
          - ready
          - running
          - finished
          - winner_found
        variants:
          description: Experiment variants
          items:
            $ref: '#/components/schemas/ExperimentVariantSummary'
          type: array
      required:
      - allocationMode
      - channelType
      - experimentType
      - id
      - meta
      - sizing
      - status
      - variants
      type: object
    ExperimentConstraints:
      description: Experiment constraints/targeting
      properties:
        suppressionListIds:
          description: List IDs to suppress
          items:
            format: int64
            type: integer
          type: array
        targetSegment:
          description: Target segment description
          type: string
      type: object
    ExperimentListItem:
      description: Summary of an experiment for list responses
      properties:
        author:
          description: Email of the experiment creator
          type: string
        channelType:
          description: Channel type for this experiment.
          type: string
          enum:
          - email
          - push
          - sms
          - in_app
          - web_push
        finishDate:
          description: Finish date of the experiment
          format: date-time
          type: string
        id:
          description: Experiment ID
          format: int64
          type: integer
        name:
          description: Experiment name
          type: string
        startDate:
          description: Start date of the experiment
          format: date-time
          type: string
        status:
          description: Experiment status
          type: string
          enum:
          - draft
          - ready
          - running
          - finished
          - winner_found
      required:
      - author
      - channelType
      - id
      - name
      - status
      type: object
    ExperimentMetricsResponse:
      properties:
        headers:
          type: string
        rows:
          description: Rows of the report.
          items:
            type: string
          type: array
      type: object
    ExperimentMeta:
      description: Experiment metadata
      properties:
        campaignId:
          description: Campaign ID
          format: int64
          type: integer
        conversionMetrics:
          description: Conversion metrics being tracked
          items:
            type: string
          type: array
        name:
          description: Experiment name
          type: string
        orgId:
          description: Organization ID
          format: int64
          type: integer
        projectId:
          description: Project ID
          format: int64
          type: integer
      required:
      - conversionMetrics
      - name
      - orgId
      - projectId
      type: object
    ExperimentSizingResponse:
      description: Experiment traffic allocation
      properties:
        holdoutPercentage:
          description: Percentage of total audience reserved as a holdout group that does not receive any experiment traffic. Null if the experiment has no holdout group configured.
          format: double
          type: number
        perVariantPercentage:
          description: Percentage of total audience distributed evenly to each variant for experiments with a blast campaign that include all users. Null for other experiment types.
          format: double
          type: number
        testGroupPercentage:
          description: Percentage of total audience used as the test group, split evenly among variants (defaults to 20%). During the test phase, Iterable sends to this group to determine which variant performs best.
          format: double
          type: number
        winnerGroupPercentage:
          description: Percentage of total audience (minus the holdout group) that receives the winning variant after the test phase completes (the optimized group). Users who already received a non-winning variant during the test phase do not receive the winner again.
          format: double
          type: number
        testDurationMinutes:
          description: How long the test phase runs before Iterable selects a winner, in minutes. Defaults to 120 minutes. Applies only to experiments with blast campaigns that are not based on a specified send time.
          format: int32
          type: integer
        sendsPerVariant:
          description: Minimum number of sends each variant must receive before the test phase ends and a winner can be selected. Defaults to 1000. Applies only to triggered campaign experiments.
          format: int32
          type: integer
      type: object
    ExperimentVariantSummary:
      description: Variant summary for experiment response
      properties:
        currentPercentage:
          description: Percentage of total audience distributed to this variant, allocated based on the type of experiment you're running.
          format: double
          type: number
        id:
          description: Variant ID
          format: int64
          type: integer
        isControl:
          description: Whether this variant is the control variant
          type: boolean
        isWinner:
          description: Whether this variant is the winner
          type: boolean
        name:
          description: Variant name
          type: string
        value:
          $ref: '#/components/schemas/ExperimentVariantValue'
          description: Typed variant value object (e.g., templateId/sendTime/stoGroup)
      required:
      - currentPercentage
      - id
      - isControl
      - isWinner
      - name
      - value
      type: object
    PaginationResponse:
      description: Pagination information for list responses
      properties:
        limit:
          description: Number of items per page
          format: int32
          type: integer
        offset:
          description: Current offset
          format: int32
          type: integer
        total:
          description: Total number of items
          format: int64
          type: integer
      required:
      - limit
      - offset
      - total
      type: object
    ExperimentListResponse:
      description: Response for listing experiments
      properties:
        experiments:
          description: List of experiments
          items:
            $ref: '#/components/schemas/ExperimentListItem'
          type: array
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
          description: Pagination information
      required:
      - experiments
      - pagination
      type: object
  securitySchemes:
    api_key:
      in: header
      name: Api-Key
      type: apiKey
    apiKeyAuth:
      type: apiKey
      in: header
      name: Api-Key
      description: Iterable API key passed in the Api-Key header. API keys can be created and managed in the Iterable project settings.
externalDocs:
  description: Iterable API Documentation
  url: https://api.iterable.com/api/docs
x-refined-from:
- iterable-api-openapi.json
- iterable-rest-api-openapi.yml