Looker Query API

openapi: 3.1.0
info:
  title: Looker Auth Query API
  description: The Looker API 4.0 provides programmatic access to the Looker business intelligence platform. It allows you to manage and interact with Looks, dashboards, queries, users, and other Looker resources. The API uses client credentials (client_id and client_secret) for authentication and returns JSON responses. Looker is part of Google Cloud and the API is available on any Looker instance at the /api/4.0 path.
  version: '4.0'
  contact:
    name: Google Cloud Looker Support
    url: https://cloud.google.com/looker/docs/support
  termsOfService: https://cloud.google.com/terms
  license:
    name: Google Cloud Terms
    url: https://cloud.google.com/terms
servers:
- url: https://{instance}.looker.com/api/4.0
  description: Looker Instance API
  variables:
    instance:
      description: Your Looker instance hostname prefix
      default: your-instance
- url: https://{instance}.cloud.looker.com/api/4.0
  description: Looker (Google Cloud core) Instance API
  variables:
    instance:
      description: Your Looker (Google Cloud core) instance hostname prefix
      default: your-instance
security:
- bearerAuth: []
tags:
- name: Query
  description: Create and run queries against your Looker models. Queries define the fields, filters, sorts, and limits used to retrieve data from the underlying database through LookML models.
paths:
  /queries:
    post:
      operationId: createQuery
      summary: Looker Create a Query
      description: Creates a new query object. A query defines the model, view, fields, filters, sorts, and limit used to retrieve data from the underlying database. The query is not executed until you call the run_query endpoint. Queries are immutable once created.
      tags:
      - Query
      parameters:
      - $ref: '#/components/parameters/fields'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WriteQuery'
      responses:
        '200':
          description: Query created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Query'
        '400':
          description: Invalid query definition
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /queries/{query_id}:
    get:
      operationId: query
      summary: Looker Get a Query
      description: Retrieves a query object by its ID. Returns the query definition including the model, view, fields, filters, sorts, and limit.
      tags:
      - Query
      parameters:
      - $ref: '#/components/parameters/queryId'
      - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Query details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Query'
        '404':
          description: Query not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /queries/{query_id}/run/{result_format}:
    get:
      operationId: runQuery
      summary: Looker Run a Saved Query
      description: Executes a previously saved query and returns results in the specified format. The query must already exist. Supported formats include json, csv, txt, xlsx, html, md, json_label, json_detail, sql, and png.
      tags:
      - Query
      parameters:
      - $ref: '#/components/parameters/queryId'
      - name: result_format
        in: path
        required: true
        description: Format for the query results
        schema:
          type: string
          enum:
          - json
          - csv
          - txt
          - xlsx
          - html
          - md
          - json_label
          - json_detail
          - sql
          - png
      - $ref: '#/components/parameters/limit'
      - name: apply_formatting
        in: query
        description: Whether to apply model-specified formatting
        schema:
          type: boolean
      - name: apply_vis
        in: query
        description: Whether to apply visualization options
        schema:
          type: boolean
      - name: cache
        in: query
        description: Whether to use cached results if available
        schema:
          type: boolean
          default: true
      - name: generate_drill_links
        in: query
        description: Whether to generate drill links in results
        schema:
          type: boolean
          default: true
      - name: force_production
        in: query
        description: Whether to force use of production models
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Query results in the requested format
          content:
            application/json:
              schema:
                type: string
            text/csv:
              schema:
                type: string
        '404':
          description: Query not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /queries/run/{result_format}:
    post:
      operationId: runInlineQuery
      summary: Looker Run an Inline Query
      description: Creates and immediately executes a query in a single request. The query definition is provided in the request body and does not need to be saved first. This is useful for ad-hoc queries.
      tags:
      - Query
      parameters:
      - name: result_format
        in: path
        required: true
        description: Format for the query results
        schema:
          type: string
          enum:
          - json
          - csv
          - txt
          - xlsx
          - html
          - md
          - json_label
          - json_detail
          - sql
          - png
      - $ref: '#/components/parameters/limit'
      - name: apply_formatting
        in: query
        description: Whether to apply model-specified formatting
        schema:
          type: boolean
      - name: apply_vis
        in: query
        description: Whether to apply visualization options
        schema:
          type: boolean
      - name: cache
        in: query
        description: Whether to use cached results
        schema:
          type: boolean
          default: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WriteQuery'
      responses:
        '200':
          description: Query results in the requested format
          content:
            application/json:
              schema:
                type: string
            text/csv:
              schema:
                type: string
        '400':
          description: Invalid query definition
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    limit:
      name: limit
      in: query
      description: Maximum number of results to return
      schema:
        type: integer
        default: 100
    fields:
      name: fields
      in: query
      description: Comma-separated list of field names to include in the response. Use this to limit response payload and improve performance.
      schema:
        type: string
    queryId:
      name: query_id
      in: path
      required: true
      description: The unique numeric ID of the query
      schema:
        type: integer
        format: int64
  schemas:
    WriteQuery:
      type: object
      required:
      - model
      - view
      description: Writable fields for creating a new query
      properties:
        model:
          type: string
          description: LookML model name
          example: example_value
        view:
          type: string
          description: LookML explore (view) name
          example: example_value
        fields:
          type: array
          description: List of field names to include
          items:
            type: string
          example: []
        pivots:
          type: array
          nullable: true
          description: Fields to pivot on
          items:
            type: string
          example: []
        fill_fields:
          type: array
          nullable: true
          description: Fields to fill missing values for
          items:
            type: string
          example: []
        filters:
          type: object
          nullable: true
          description: Filter expressions keyed by field name
          additionalProperties:
            type: string
          example: example_value
        filter_expression:
          type: string
          nullable: true
          description: Custom filter expression
          example: example_value
        sorts:
          type: array
          nullable: true
          description: Sort order for results
          items:
            type: string
          example: []
        limit:
          type: string
          nullable: true
          description: Maximum rows to return
          example: example_value
        column_limit:
          type: string
          nullable: true
          description: Maximum columns for pivoted results
          example: example_value
        total:
          type: boolean
          description: Include row totals
          example: true
        row_total:
          type: string
          nullable: true
          description: Row total setting
          example: example_value
        subtotals:
          type: array
          nullable: true
          description: Fields to subtotal on
          items:
            type: string
          example: []
        dynamic_fields:
          type: string
          nullable: true
          description: JSON string of dynamic field definitions
          example: example_value
        vis_config:
          type: object
          nullable: true
          description: Visualization configuration
          additionalProperties: true
          example: example_value
        query_timezone:
          type: string
          nullable: true
          description: Timezone for date/time calculations
          example: example_value
    ErrorResponse:
      type: object
      description: Error response from the Looker API
      properties:
        message:
          type: string
          description: Human-readable error message
          example: example_value
        documentation_url:
          type: string
          description: URL to relevant API documentation
          example: https://www.example.com
    Query:
      type: object
      description: A query defines a data request against a LookML model. Queries are immutable once created and contain the model, view, fields, filters, sorts, and limit needed to generate SQL and retrieve results.
      properties:
        id:
          type: integer
          format: int64
          description: Unique numeric identifier for this query
          readOnly: true
          example: abc123
        model:
          type: string
          description: LookML model name
          example: example_value
        view:
          type: string
          description: LookML explore (view) name
          example: example_value
        fields:
          type: array
          description: List of field names to include in the query results (e.g. orders.count, users.created_date)
          items:
            type: string
          example: []
        pivots:
          type: array
          nullable: true
          description: List of field names to pivot on
          items:
            type: string
          example: []
        fill_fields:
          type: array
          nullable: true
          description: Fields to fill missing date values for
          items:
            type: string
          example: []
        filters:
          type: object
          nullable: true
          description: Key-value map of filter expressions. Keys are field names and values are Looker filter expressions.
          additionalProperties:
            type: string
          example: example_value
        filter_expression:
          type: string
          nullable: true
          description: Custom filter expression using Looker filter syntax
          example: example_value
        sorts:
          type: array
          nullable: true
          description: Sort order for results. Each item is a field name optionally followed by asc or desc.
          items:
            type: string
          example: []
        limit:
          type: string
          nullable: true
          description: Maximum number of rows to return (as string)
          example: example_value
        column_limit:
          type: string
          nullable: true
          description: Maximum number of columns for pivoted results
          example: example_value
        total:
          type: boolean
          description: Whether to include row totals
          example: true
        row_total:
          type: string
          nullable: true
          description: Row total display setting
          example: example_value
        subtotals:
          type: array
          nullable: true
          description: Fields to subtotal on
          items:
            type: string
          example: []
        dynamic_fields:
          type: string
          nullable: true
          description: JSON string of dynamic field definitions
          example: example_value
        vis_config:
          type: object
          nullable: true
          description: Visualization configuration object
          additionalProperties: true
          example: example_value
        query_timezone:
          type: string
          nullable: true
          description: Timezone for date/time calculations
          example: example_value
        client_id:
          type: string
          description: Client-generated hash of the query for caching
          readOnly: true
          example: '500123'
        slug:
          type: string
          description: Short unique URL slug for this query
          readOnly: true
          example: example_value
        share_url:
          type: string
          description: Shareable URL for this query
          readOnly: true
          example: https://www.example.com
        url:
          type: string
          description: Relative URL for this query in the Looker UI
          readOnly: true
          example: https://www.example.com
        has_table_calculations:
          type: boolean
          description: Whether this query has table calculations
          readOnly: true
          example: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Access token obtained from the /login endpoint using client credentials. Include as Bearer token in the Authorization header.
externalDocs:
  description: Looker API 4.0 Documentation
  url: https://cloud.google.com/looker/docs/reference/looker-api/latest