openapi: 3.2.0
info:
  title: Treasure Data Schedules API
  version: '3'
servers:
- url: https://api.treasuredata.com/v3
- url: https://api.treasuredata.co.jp/v3
- url: https://api.ap02.treasuredata.com/v3
- url: https://api.eu01.treasuredata.com/v3
security:
- ApiKeyAuth: []
tags:
- name: Schedules
paths:
  /schedule/list:
    get:
      summary: Get schedules
      description: Gets a list of schedules.
      operationId: getSchedules
      tags:
      - Schedules
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - schedules
                properties:
                  schedules:
                    type: array
                    items:
                      $ref: '#/components/schemas/Schedule'
  /schedule/create/{schedule_name}:
    post:
      summary: Create schedule
      description: Creates a schedule.
      operationId: createSchedule
      tags:
      - Schedules
      parameters:
      - $ref: '#/components/parameters/path_schedule_name'
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              allOf:
              - $ref: '#/components/schemas/CreateOrUpdateScheduleRequest'
              - type: object
                required:
                - database
                - query
                - type
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleReference'
  /schedule/delete/{schedule_name}:
    post:
      summary: Delete schedule
      description: Deletes a specified schedule.
      operationId: deleteScheduleByName
      tags:
      - Schedules
      parameters:
      - $ref: '#/components/parameters/path_schedule_name'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleReference'
  /schedule/update/{schedule_name}:
    post:
      summary: Update schedule
      description: Updates a schedule.
      operationId: updateSchedule
      tags:
      - Schedules
      parameters:
      - $ref: '#/components/parameters/path_schedule_name'
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreateOrUpdateScheduleRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleReference'
  /schedule/run/{schedule_name}/{schedule_time}:
    post:
      summary: Run schedule
      description: Schedules a run.
      operationId: runSchedule
      tags:
      - Schedules
      parameters:
      - $ref: '#/components/parameters/path_schedule_name'
      - name: schedule_time
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/Timestamp'
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              additionalProperties: false
              properties:
                num:
                  type: integer
                  default: 1
                  maximum: 10
                domain_key:
                  $ref: '#/components/schemas/DomainKey'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - jobs
                properties:
                  jobs:
                    type: array
                    items:
                      $ref: '#/components/schemas/ScheduledJob'
  /schedule/history/{schedule_name}:
    get:
      summary: Get execution history
      description: Gets a history of scheduled executions by name.
      operationId: getScheduleExecutionHistoryByName
      tags:
      - Schedules
      parameters:
      - $ref: '#/components/parameters/path_schedule_name'
      - name: from
        in: query
        schema:
          type: integer
          default: 0
      - name: to
        in: query
        schema:
          type: integer
          default: 20
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - count
                - from
                - to
                - history
                properties:
                  count:
                    type: integer
                    example: 20
                  from:
                    type: integer
                    example: 5
                  to:
                    type: integer
                    example: 15
                  history:
                    type: array
                    items:
                      allOf:
                      - $ref: '#/components/schemas/Job'
                      - type: object
                        required:
                        - scheduled_at
                        properties:
                          scheduled_at:
                            oneOf:
                            - $ref: '#/components/schemas/DateTimeAsString'
                            - $ref: '#/components/schemas/EmptyString'
components:
  schemas:
    ScheduleReference:
      type: object
      required:
      - created_at
      - cron
      - database
      - delay
      - name
      - query
      - timezone
      - type
      - user_name
      properties:
        created_at:
          $ref: '#/components/schemas/DateTimeISO8601'
        cron:
          $ref: '#/components/schemas/Schedule/properties/cron'
        database:
          $ref: '#/components/schemas/Schedule/properties/database'
        delay:
          $ref: '#/components/schemas/Schedule/properties/delay'
        name:
          $ref: '#/components/schemas/Schedule/properties/name'
        query:
          $ref: '#/components/schemas/Schedule/properties/query'
        timezone:
          $ref: '#/components/schemas/Timezone'
        type:
          $ref: '#/components/schemas/Schedule/properties/type'
        user_name:
          $ref: '#/components/schemas/User/properties/name'
    JobId:
      description: unique identifier of job
      type: integer
      example: 19
    Job:
      title: Job
      description: an execution of a query
      type: object
      required:
      - cpu_time
      - created_at
      - database
      - duration
      - end_at
      - hive_result_schema
      - job_id
      - linked_result_export_job_id
      - num_records
      - organization
      - priority
      - query
      - result_export_target_job_id
      - result_size
      - retry_limit
      - start_at
      - status
      - type
      - updated_at
      - url
      - user_name
      properties:
        cpu_time:
          type:
          - integer
          - 'null'
        created_at:
          $ref: '#/components/schemas/DateTimeAsString'
        database:
          description: database name
          type:
          - string
          - 'null'
        duration:
          description: Duration
          type:
          - integer
          - 'null'
          example: 10
        end_at:
          oneOf:
          - $ref: '#/components/schemas/DateTimeAsString'
          - $ref: '#/components/schemas/EmptyString'
        hive_result_schema:
          description: the schema for the job's result table
          type:
          - string
          - 'null'
        job_id:
          $ref: '#/components/schemas/JobIdAsString'
        linked_result_export_job_id:
          anyOf:
          - $ref: '#/components/schemas/JobId'
          - description: result job id
            type:
            - integer
            - 'null'
        num_records:
          description: the number of records in the result. Will be `null` until job has finished, and may not be set for all query types
          type:
          - integer
          - 'null'
          example: 100
        organization:
          description: always "null"
          type:
          - string
          - 'null'
          deprecated: true
        priority:
          description: job execution priority
          type: integer
          minimum: -2
          maximum: 2
          example: 0
        query:
          anyOf:
          - type:
            - string
            - 'null'
          - $ref: '#/components/schemas/QueryAsString'
          - $ref: '#/components/schemas/BulkLoadConfig'
        result:
          description: URL of the result output destination
          type: string
        result_export_target_job_id:
          anyOf:
          - $ref: '#/components/schemas/JobId'
          - description: result export job id
            type:
            - integer
            - 'null'
        result_size:
          description: size in bytes of the job's result, in `msgpack.gz` format
          type:
          - integer
          - 'null'
          example: 1048576
        retry_limit:
          description: automatically retry this many times on failure
          type: integer
          default: 0
          minimum: 0
          maximum: 32
          example: 3
        start_at:
          oneOf:
          - $ref: '#/components/schemas/DateTimeAsString'
          - $ref: '#/components/schemas/EmptyString'
        status:
          description: current status of the job
          type: string
          enum:
          - queued
          - running
          - killed
          - success
          - error
          example: success
        type:
          type: string
          example: presto
        updated_at:
          $ref: '#/components/schemas/DateTimeAsString'
        url:
          type: string
        user_name:
          $ref: '#/components/schemas/User/properties/name'
    Schedule:
      type: object
      required:
      - created_at
      - cron
      - database
      - delay
      - name
      - query
      - timezone
      - type
      - user_name
      properties:
        created_at:
          $ref: '#/components/schemas/DateTimeISO8601'
        cron:
          type:
          - string
          - 'null'
        database:
          anyOf:
          - $ref: '#/components/schemas/Database/properties/name'
          - type:
            - string
            - 'null'
        delay:
          type:
          - integer
          - 'null'
          minimum: 0
          example: 5
        engine_version:
          description: the version of the query engine for the query, can be a version release name (e.g 'stable') or version number (e.g '0.205')
          type: string
          example: stable
        executing_user_id:
          type: integer
        name:
          type: string
        priority:
          type: integer
          minimum: -2
          maximum: 2
          example: 1
        query:
          type: string
        retry_limit:
          type: integer
          minimum: 0
          maximum: 32
          example: 3
        timezone:
          $ref: '#/components/schemas/Timezone'
        type:
          type: string
        user_name:
          $ref: '#/components/schemas/User/properties/name'
    EmptyString:
      type: string
      pattern: ^$
    ScheduledJob:
      type: object
      additionalProperties: false
      required:
      - job_id
      - type
      - scheduled_at
      properties:
        job_id:
          $ref: '#/components/schemas/JobId'
        type:
          $ref: '#/components/schemas/Job/properties/type'
        scheduled_at:
          oneOf:
          - $ref: '#/components/schemas/DateTimeAsString'
          - $ref: '#/components/schemas/EmptyString'
    QueryAsString:
      description: the raw SQL query
      type: string
      example: SELECT * FROM my_table;
    DateTimeAsString:
      description: Datetime in custom format (`2020-12-31 11:22:33 -0500` or `2020-12-31 11:22:33 UTC` for UTC)
      type: string
      pattern: \d{4}-\d{2}-\d{2}\s\d{2}:\d{2}:\d{2}\s(([+-]\d{2}\d{2})|UTC)
      example: 2020-12-31 11:22:33 UTC
    Database:
      title: Database
      description: Database
      type: object
      additionalProperties: false
      required:
      - count
      - created_at
      - delete_protected
      - name
      - organization
      - permission
      - updated_at
      properties:
        count:
          description: ???
          type: integer
          example: 5
        created_at:
          $ref: '#/components/schemas/DateTimeAsString'
        delete_protected:
          description: wheter the database is delete protected
          type: boolean
          example: true
        datatank:
          type: boolean
        id:
          $ref: '#/components/schemas/DatabaseIdAsString'
        name:
          description: database name
          type: string
          example: Alpha
        organization:
          description: the organization
          type:
          - string
          - 'null'
          example: Treasure Data
        permission:
          description: permissions
          type:
          - string
          - 'null'
        database_permissions:
          description: permissions
          type: object
          additionalProperties: true
          properties:
            edit:
              description: edit permission for database
              type: boolean
            delete:
              description: delete permission for database
              type: boolean
            query:
              description: query permission for database
              type: boolean
            import:
              description: import permission for database
              type: boolean
            download:
              description: download permission for database
              type: boolean
        updated_at:
          $ref: '#/components/schemas/DateTimeAsString'
    Timezone:
      type: string
      example: UTC
    BulkLoadConfig:
      title: BulkLoadConfig
      description: bulk load config
      type: object
      additionalProperties: true
      properties:
        in:
          type: object
          additionalProperties: true
          properties:
            connection_prop:
              type: string
              example: connection_prop
            connection_secret:
              type: string
              example: secret
            basic_prop:
              type: string
              example: basic
            basic_secret:
              type: string
              example: secret
            advanced_prop:
              type: string
              example: advanced
            advanced_secret:
              type: string
              example: secret
            type:
              type: string
              example: some_type
            td_authentication_id:
              type: integer
              example: 1234
        filters:
          type: array
          items:
            type: object
        exec:
          type: object
          additionalProperties: true
          properties:
            type:
              type: string
              example: some_type
            basic_prop:
              type: string
              example: basic
            secret_prop:
              type: string
              example: secret
        out:
          type: object
          additionalProperties: true
          properties:
            type:
              type: string
              example: some_type
            mode:
              type: string
              example: mode
            plazma_dataset:
              type: string
              example: plazma
            time_column:
              type: string
              example: time
    User:
      title: User
      description: User
      type: object
      additionalProperties: false
      required:
      - id
      - account_owner
      - administrator
      - created_at
      - email
      - first_name
      - gravatar_url
      - last_name
      - phone
      - updated_at
      properties:
        id:
          $ref: '#/components/schemas/UserId'
        account_owner:
          description: whether the user is Account owner or not
          type: boolean
          example: true
        administrator:
          description: whether the user is Administrator or not
          type: boolean
          example: true
        created_at:
          $ref: '#/components/schemas/DateTimeISO8601'
        email:
          description: the email user uses to log in
          type: string
          format: email
          example: td@example.com
        first_name:
          description: first name
          type:
          - string
          - 'null'
          example: Treasure
        gravatar_url:
          description: gravatar url
          type: string
          example: http://foo
        identifier:
          $ref: '#/components/schemas/SSOIdentifier'
        full_qualified_identifier:
          $ref: '#/components/schemas/SSOFullQualifiedIdentifier'
        setting_name:
          $ref: '#/components/schemas/SSOSettingName'
        last_name:
          description: last name
          type:
          - string
          - 'null'
          example: Data
        name:
          description: user's full name or email
          type: string
          example: Treasure Data
        organization:
          deprecated: true
          type:
          - string
          - 'null'
        phone:
          description: phone number
          type:
          - string
          - 'null'
          example: (650) 469-3644
        roles:
          deprecated: true
          type: array
          items:
            type: string
        updated_at:
          $ref: '#/components/schemas/DateTimeISO8601'
        delegated_admin:
          description: whether the user is a Delegated Admin or not. This attribute is available if the account enables the delegated-admin feature flag.
          type: boolean
          example: true
        delegated_policy_groups:
          description: The list of policy groups this user manages as delegated admin. This attribute is available if the account enables the delegated-admin feature flag.
          type: array
          items:
            type: string
        policy_group_tags:
          description: The list of tag names belonging to this user. This attribute is available if the account enables the delegated-admin feature flag.
          type: array
          items:
            type: string
    DomainKey:
      type: string
      example: domain_key_123
    CreateOrUpdateScheduleRequest:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/Schedule/properties/name'
        cron:
          $ref: '#/components/schemas/Schedule/properties/cron'
        database:
          $ref: '#/components/schemas/Database/properties/name'
        delay:
          $ref: '#/components/schemas/Schedule/properties/delay'
        executing_user_id:
          $ref: '#/components/schemas/Schedule/properties/executing_user_id'
        engine_version:
          $ref: '#/components/schemas/Schedule/properties/engine_version'
        pool_name:
          description: resource pool name
          type: string
          example: pool_1
        priority:
          $ref: '#/components/schemas/Schedule/properties/priority'
        retry_limit:
          $ref: '#/components/schemas/Schedule/properties/retry_limit'
        query:
          $ref: '#/components/schemas/Schedule/properties/query'
        result:
          description: url of the result
          type: string
        timezone:
          $ref: '#/components/schemas/Timezone'
        type:
          $ref: '#/components/schemas/Schedule/properties/type'
    Timestamp:
      type: integer
      example: 1356998400
    JobIdAsString:
      description: unique identifier of job
      type: string
      example: '19'
    DateTimeISO8601:
      description: Datetime in ISO 8601 format (`2020-12-31T11:22:33-05:00` or `2020-12-31T11:22:33Z` for UTC)
      type: string
      pattern: \d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(([+-]\d{2}:\d{2})|Z)
      example: '2020-12-31T11:22:33Z'
  parameters:
    path_schedule_name:
      name: schedule_name
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Schedule/properties/name'
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: TD1