> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dune.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Query Schedule

> Run a saved query on a schedule. Creates the schedule, or replaces all the settings of the one the query has. Every run is charged credits at the chosen performance tier. You need to own the query or be an editor or admin of the team that owns it; a team API key can only schedule its own team's queries.

> [!NOTE]
>
> Minimum required API key scope: `Read/Write`

# Use Cases

* **Keep Results Fresh**: Run a query every few hours, then read the latest result without executing it yourself.
* **Change a Schedule**: Change the frequency or performance tier. The response has `created: false` when it replaced a schedule.
* **Safe Retries**: The call is idempotent. Sending the same settings again leaves one schedule with those settings.


## OpenAPI

````yaml PUT /v1/queries/{query_id}/schedule
openapi: 3.0.1
info:
  contact: {}
  description: Dune API
  title: DuneAPI
  version: '1.0'
servers:
  - url: https://api.dune.com/api
security: []
paths:
  /v1/queries/{query_id}/schedule:
    put:
      summary: Set a query schedule
      description: >-
        Run a saved query on a schedule. Creates the schedule, or replaces all
        the settings of the one the query has. Every run is charged credits at
        the chosen performance tier. You need to own the query or be an editor
        or admin of the team that owns it; a team API key can only schedule its
        own team's queries.
      parameters:
        - description: API Key for the service
          in: header
          name: X-Dune-Api-Key
          required: true
          schema:
            type: string
        - description: Query ID
          in: path
          name: query_id
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/models.SetScheduleRequest'
        description: Schedule settings
        required: true
        x-originalParamName: body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.SetScheduleResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.Error400'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.Error401'
          description: Unauthorized
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.Error402'
          description: Payment Required
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.Error403'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.Error404'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.Error409'
          description: Conflict
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.Error500'
          description: Internal Server Error
components:
  schemas:
    models.SetScheduleRequest:
      properties:
        cron_expression:
          description: >-
            CronExpression is a 5-part cron expression in UTC. Supported: every
            15, 20 or 30

            minutes ("*/15 * * * *"), hourly ("0 * * * *"), every 2, 3, 4, 6, 8
            or 12 hours

            ("0 */6 * * *"), daily ("M H * * *") and weekly ("M H * * D"), where
            M is 0 or 30.
          example: 0 6 * * *
          type: string
        expires_at:
          description: >-
            ExpiresAt stops the schedule after this time. Omitted means no
            expiration; the free

            plan caps it at 3 months.
          type: string
        performance:
          description: >-
            Performance is the engine tier each run uses and must be available
            on your plan.

            Every run is charged credits at this tier.
          enum:
            - small
            - medium
            - large
          example: medium
          type: string
      required:
        - cron_expression
        - performance
      type: object
    models.SetScheduleResponse:
      properties:
        created:
          description: >-
            Created is true when the request created the schedule, false when it
            replaced one.
          type: boolean
        cron_expression:
          description: CronExpression is a 5-part cron expression in UTC.
          example: 0 6 * * *
          type: string
        dashboard_id:
          description: DashboardID is set for dashboard schedules.
          type: integer
        expires_at:
          description: ExpiresAt is absent when the schedule does not expire.
          type: string
        next_execution_time:
          type: string
        performance:
          description: Performance is the engine tier each run uses.
          enum:
            - small
            - medium
            - large
          example: medium
          type: string
        query_id:
          description: QueryID is set for query and materialized view schedules.
          example: 1234567
          type: integer
        type:
          description: >-
            Type is what the schedule runs. Materialized view refreshes are
            managed through the

            /v1/materialized-views endpoints.
          enum:
            - query
            - dashboard
            - materialized_view
          example: query
          type: string
      type: object
    models.Error400:
      properties:
        error:
          example: Bad Request
          type: string
      type: object
    models.Error401:
      properties:
        error:
          example: Invalid API Key
          type: string
      type: object
    models.Error402:
      properties:
        error:
          example: >-
            This API request would exceed your configured limits per billing
            cycle.
          type: string
      type: object
    models.Error403:
      properties:
        error:
          example: >-
            Not allowed to execute query. Query is archived, unsaved or not
            enough permissions
          type: string
      type: object
    models.Error404:
      properties:
        error:
          example: Object not found
          type: string
      type: object
    models.Error409:
      properties:
        error:
          example: Conflict - The request conflicts with another request.
          type: string
      type: object
    models.Error500:
      properties:
        error:
          example: Internal error
          type: string
      type: object

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.