Dune Analytics Endpoints API

openapi: 3.2.0
info:
  contact: {}
  description: Dune API
  title: Dune Endpoints API
  version: '1.0'
servers:
- url: https://api.dune.com/api
tags:
- name: Endpoints
paths:
  /v1/endpoints/{handle}/{endpoint_slug}/results:
    get:
      description: Create custom API endpoints from Dune queries
      parameters:
      - description: API Key for the service
        in: header
        name: X-Dune-Api-Key
        required: true
        schema:
          type: string
      - description: API Key, alternative to using the HTTP header X-Dune-Api-Key
        in: query
        name: api_key
        schema:
          type: string
      - description: Your user or team handle
        in: path
        name: handle
        required: true
        schema:
          type: string
      - description: The name of the endpoint as slug
        in: path
        name: endpoint_slug
        required: true
        schema:
          type: string
      - description: 'This enables returning a query result that was too large and only a partial result is

          available. By default, allow_partial_results is set to false and a failed state is returned.'
        in: query
        name: allow_partial_results
        schema:
          type: boolean
      - description: 'Specifies a comma-separated list of column names to return. If omitted, all columns are included.

          Tip: use this to limit the result to specific columns, reducing datapoints cost of the call.'
        in: query
        name: columns
        schema:
          type: string
      - description: 'Expression to filter out rows from the results to return. This expression is similar to

          a SQL WHERE clause. More details about it in the Filtering section of the doc.

          This parameter is incompatible with sample_count.'
        in: query
        name: filters
        schema:
          type: string
      - description: To bypass the default max credits per request limit, set ignore_max_credits_per_request=true
        in: query
        name: ignore_max_credits_per_request
        schema:
          type: boolean
      - description: 'Limit number of rows to return. This together with ''offset'' allows easy pagination through

          results in an incremental and efficient way. This parameter is incompatible

          with sampling (sample_count).'
        in: query
        name: limit
        schema:
          type: integer
      - description: 'Offset row number to start (inclusive, first row means offset=0) returning results

          from. This together with ''limit'' allows easy pagination through results in an

          incremental and efficient way. This parameter is incompatible with sampling (sample_count).'
        in: query
        name: offset
        schema:
          type: integer
      - in: query
        name: queryID
        required: true
        schema:
          type: integer
      - description: 'Number of rows to return from the result by sampling the data. This is useful when you

          want to get a uniform sample instead of the entire result. If the result has less

          than the sample count, the entire result is returned. Note that this will return a

          randomized sample, so not every call will return the same result. This parameter is

          incompatible with `offset`, `limit`, and `filters` parameters.'
        in: query
        name: sample_count
        schema:
          type: integer
      - description: 'Expression to define the order in which the results should be returned. This expression

          is similar to a SQL ORDER BY clause. More details about it in the Sorting section of the doc.'
        in: query
        name: sort_by
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ReadExecutionResultResponse'
          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
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.Error500'
          description: Internal Server Error
      summary: Custom Endpoints
      x-required-scope: Read
      tags:
      - Endpoints
      operationId: getV1EndpointsByHandleByEndpointSlugResults
      x-operation-id-source: derived
components:
  schemas:
    models.Error400:
      properties:
        error:
          example: Bad Request
          type: string
      type: object
    models.QueryResultData:
      properties:
        metadata:
          allOf:
          - $ref: '#/components/schemas/models.ExecutionResultMetadata'
          description: 'Metadata about the execution of the query, including details like column names,

            row counts, and execution times.'
        rows:
          description: 'A list of rows. A row is dictionary of key-value pairs returned by the query,

            each pair corresponding to a column'
          items:
            $ref: '#/components/schemas/models.Row'
          type: array
        update_type:
          description: The type of update operation from Trino (e.g., "SET SESSION")
          type: string
      type: object
    models.ReadExecutionResultResponse:
      properties:
        cancelled_at:
          description: Timestamp of when the query execution was cancelled, if applicable.
          example: '2024-12-20T11:04:18.724658237Z'
          type: string
        error:
          allOf:
          - $ref: '#/components/schemas/models.QueryResultError'
          description: In case the execution had an error, this object will contain the error details
        execution_ended_at:
          description: Timestamp of when the query execution ended.
          example: '2024-12-20T11:04:18.724658237Z'
          type: string
        execution_id:
          description: Unique identifier for the execution of the query.
          example: 01HKZJ2683PHF9Q9PHHQ8FW4Q1
          type: string
        execution_started_at:
          description: Timestamp of when the query execution started.
          example: '2024-12-20T11:04:18.724658237Z'
          type: string
        expires_at:
          description: Timestamp of when the query result expires.
          example: '2024-12-20T11:04:18.724658237Z'
          type: string
        is_execution_finished:
          description: Whether the state of the query execution is terminal. This can be used for polling purposes.
          example: true
          type: boolean
        next_offset:
          description: Offset that can be used to retrieve the next page of results.
          example: 100
          type: integer
        next_uri:
          description: URI that can be used to fetch the next page of results.
          example: https://api.dune.com/api/v1/execution/01HKZJ2683PHF9Q9PHHQ8FW4Q1/results?offset=100&limit=100
          type: string
        query_id:
          description: Unique identifier of the query.
          example: 1234
          type: integer
        result:
          allOf:
          - $ref: '#/components/schemas/models.QueryResultData'
          description: The object containing the results and metadata of the query execution
        state:
          description: The state of the query execution.
          example: QUERY_STATE_COMPLETED
          type: string
        submitted_at:
          description: Timestamp of when the query was submitted.
          example: '2024-12-20T11:04:18.724658237Z'
          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.Error402:
      properties:
        error:
          example: This API request would exceed your configured limits per billing cycle.
          type: string
      type: object
    models.QueryResultError:
      properties:
        message:
          description: A descriptive message about the error.
          example: 'Error: Line 1:1: mismatched input ''selecdt'''
          type: string
        metadata:
          allOf:
          - $ref: '#/components/schemas/models.SyntaxErrorMetadata'
          description: Metadata about the syntax error that occurred, if applicable.
        type:
          description: The type of error that occurred.
          example: syntax_error
          type: string
      type: object
    models.Row:
      additionalProperties: {}
      type: object
    models.ExecutionResultMetadata:
      properties:
        column_names:
          description: Names of the columns in the result set.
          example:
          - Rank
          - Project
          - Volume
          items:
            type: string
          type: array
        column_types:
          description: Types of the columns in the result set.
          example:
          - double
          - varchar
          - bigint
          items:
            type: string
          type: array
        datapoint_count:
          description: 'Results cell count is used for billing/pricing plans

            here we expose the these values to the user, so that they can track their costs'
          example: 1000
          type: integer
        execution_time_millis:
          description: Time in milliseconds that the query took to execute.
          example: 1000
          type: integer
        pending_time_millis:
          description: Time in milliseconds that the query was pending before execution.
          example: 1000
          type: integer
        result_set_bytes:
          description: "ResultSetBytes represents the raw data bytes returned by the SQL execution engine, it includes:\n + total nr of bytes used on 1 line with all the column names (the header of the result set)\n + total nr of bytes for all the row values (the result set of rows)\n\nit doesn't include overheads such as the presence of column names for every row in the JSON result type.\nit also doesn't include opmitizations such as compression"
          example: 1000
          type: integer
        row_count:
          description: Number of rows in the result set for the current page of results.
          example: 10
          type: integer
        total_result_set_bytes:
          description: Total number of bytes in the result set. This doesn't include the json representation overhead.
          example: 10000
          type: integer
        total_row_count:
          description: Number of rows in the result set for the entire result set.
          example: 1000
          type: integer
      type: object
    models.SyntaxErrorMetadata:
      properties:
        column:
          description: The column number at which the syntax error occurred.
          example: 73
          type: integer
        line:
          description: The line number at which the syntax error occurred in the query.
          example: 10
          type: integer
      type: object
    models.Error401:
      properties:
        error:
          example: Invalid API Key
          type: string
      type: object
    models.Error500:
      properties:
        error:
          example: Internal error
          type: string
      type: object
x-service-info:
  categories:
  - data
  - compute
  docs:
    apiReference: https://docs.dune.com/api-reference/overview/introduction
    homepage: https://docs.dune.com
x-provenance:
  method: harvested
  publisher: Dune Analytics
  source: https://api.dune.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)