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

# Query SQL

> Query records and lists with SQL. Your workspace must be on the Enterprise plan in order to access this endpoint.

This endpoint is rate limited to 2 requests per second.

This endpoint is in beta. We will aim to avoid breaking changes, but small updates may be made as we roll out to more users.

Required scopes: `record_permission:read`, `object_configuration:read`.

Supported token levels: `workspace`, `user`.



## OpenAPI

````yaml https://api.attio.com/openapi/api post /v2/sql
openapi: 3.1.0
info:
  title: Attio API
  version: 2.0.0
  contact:
    name: Attio Support
    email: support@attio.com
    url: https://attio.com/help
servers:
  - url: https://api.attio.com
    description: Production
security:
  - oauth2: []
tags:
  - name: Objects
    description: >-
      Objects are the core data models inside of Attio. They contain standard
      objects, such as
      [people](/rest-api/endpoint-reference/standard-objects/people/list-person-records),
      [companies](/rest-api/endpoint-reference/standard-objects/companies/list-company-records)
      or [deals](/docs/standard-objects-deals), and custom objects that are
      specific to your use-case. See our [objects and lists
      guide](/docs/objects-and-lists) for more information.
  - name: Activities
    description: >-
      Activities model event-based data that can be logged against a record, for
      example a phone call. Each activity extends a schema, which supplies the
      attributes that every activity of that kind shares.
  - name: Views
    description: Views are saved table or board layouts for an object or a list.
  - name: Attributes
    description: >-
      Attributes model properties of objects, lists and activities. Some
      attributes, such as the `name` attribute on a person, are system-defined,
      while others are user-defined. Attributes are one of [many
      types](/docs/attribute-types) such as text, location or select. See our
      [objects and lists guide](/docs/objects-and-lists) for more information.
  - name: Records
    description: >-
      Records are individual instances of objects e.g. a specific
      [person](/rest-api/endpoint-reference/standard-objects/people/list-person-records)
      or
      [company](/rest-api/endpoint-reference/standard-objects/companies/list-company-records).
      See our [objects and lists guide](/docs/objects-and-lists) for more
      information.
  - name: Activity records
    description: >-
      Activity records are individual instances of activities, for example one
      specific phone call.
  - name: SCIM groups
    description: >-
      SCIM groups represent Attio teams managed through the SCIM provisioning
      protocol.
  - name: SCIM schemas
    description: >-
      SCIM schemas describe the resource types supported by the SCIM service
      provider.
  - name: SCIM users
    description: >-
      SCIM users represent workspace members managed through the SCIM
      provisioning protocol.
  - name: Lists
    description: >-
      Lists are used to model a particular process. A list contains many records
      of a single object type, where each record is represented by an entry.
      Entries contain their own data from attributes defined on the list and
      also data from their parent record. See our [objects and lists
      guide](/docs/objects-and-lists) for more information.
  - name: Meta
    description: Meta endpoints are used to get information about the API token.
  - name: Entries
    description: >-
      Entries are elements in a list that reference a single parent record.
      Entries contain their own data from attributes defined on the list and
      also data from their parent record. See our [objects and lists
      guide](/docs/objects-and-lists) for more information.
  - name: Files
    description: >-
      Files are documents and folders linked to records, stored either in Attio
      or connected via external storage providers.
  - name: Workspace members
    description: >-
      Workspace members represent a user with access to a workspace. Workspace
      members are assigned roles that determine what they can do within the
      workspace.
  - name: Notes
    description: Notes are rich text documents that reference a single parent record.
  - name: Meetings
    description: >-
      Meetings are events synced from your calendar, added manually or added
      from third-party integrations.
  - name: Emails
    description: Emails are messages synced from connected mailboxes.
  - name: Sequences
    description: Sequences are automated email campaigns sent from Attio.
  - name: Workspace blocklist
    description: >-
      An address is an email address (jane@acme.com) or a domain (acme.com). The
      workspace blocklist is the workspace-wide list of addresses whose emails
      and calendar events are hidden in Attio. An email address matches only
      itself, and a domain matches every email address at that domain. The
      address itself is the key: there is no separate ID.
  - name: Call recordings
    description: >-
      Call recordings store video, audio, transcript and speaker information for
      calls. They are linked to meetings.
  - name: Transcripts
    description: >-
      Transcripts contain the speech segments and speaker information for a call
      recording. They are linked to call recordings.
  - name: Tasks
    description: >-
      A task is a defined, actionable item with references to linked records and
      assigned workspace members.
  - name: Webhooks
    description: >-
      Webhooks allow you to listen for changes to data in Attio, for example
      when a record is updated.
  - name: Threads
    description: >-
      Threads are groups of
      [comments](/rest-api/endpoint-reference/comments/get-a-comment) on either
      a record or entry.
  - name: Comments
    description: >-
      Comments are messages on a
      [thread](/rest-api/endpoint-reference/threads/list-threads).
  - name: People
    description: >-
      People are one of the core objects inside of Attio. Person records can be
      added to lists and can be created automatically when syncing your mailbox.
  - name: Companies
    description: >-
      Companies are one of the core objects inside of Attio. Company records can
      be added to lists and can be created automatically when syncing your
      mailbox.
  - name: Users
    description: >-
      Users are an optional standard object that represents a user of your
      system. Users can belong to many workspaces.
  - name: Deals
    description: >-
      Deals are an optional standard object that represent a deal or
      opportunity.
  - name: Workspaces
    description: >-
      Workspaces are an optional standard object that represent a workspace or
      account in your system. Workspaces have many users and can be used to
      model a multi-tenant system. A company record can optionally have multiple
      workspaces.
  - name: SQL
    description: >-
      Query records and list entries across your workspace using SQL. A single
      query can reference any object or list in the workspace.
paths:
  /v2/sql:
    post:
      tags:
        - SQL
      summary: Query SQL
      description: >-
        Query records and lists with SQL. Your workspace must be on the
        Enterprise plan in order to access this endpoint.


        This endpoint is rate limited to 2 requests per second.


        This endpoint is in beta. We will aim to avoid breaking changes, but
        small updates may be made as we roll out to more users.


        Required scopes: `record_permission:read`, `object_configuration:read`.


        Supported token levels: `workspace`, `user`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sql:
                  type: string
                  description: >-
                    The SQL query to be executed. Use `$name` placeholders to
                    reference values from `parameters` instead of inlining them
                    into the query.
                  example: >-
                    SELECT * FROM companies WHERE (name = $name OR name =
                    ANY($names)) AND created_at >= $since
                parameters:
                  type: object
                  additionalProperties:
                    oneOf:
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - 'null'
                            description: The type of the parameter.
                        required:
                          - type
                        additionalProperties: false
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - boolean
                            description: The type of the parameter.
                          value:
                            type: boolean
                            example: true
                        required:
                          - type
                          - value
                        additionalProperties: false
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - integer
                            description: The type of the parameter.
                          value:
                            type: integer
                            minimum: -9007199254740991
                            maximum: 9007199254740991
                            description: An integer between -(2^53 - 1) and 2^53 - 1.
                            example: 100
                        required:
                          - type
                          - value
                        additionalProperties: false
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - double
                            description: The type of the parameter.
                          value:
                            type: number
                            example: 3.14
                        required:
                          - type
                          - value
                        additionalProperties: false
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - string
                            description: The type of the parameter.
                          value:
                            type: string
                            example: Fundstack
                        required:
                          - type
                          - value
                        additionalProperties: false
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - timestamp
                            description: The type of the parameter.
                          value:
                            type: string
                            format: date-time
                            description: >-
                              An ISO 8601 timestamp with a time zone, either `Z`
                              or an offset such as `+02:00` or `+0200`, e.g.
                              `2023-01-01T15:00:00.123456Z`. Seconds and
                              fractional seconds are optional. Truncated to
                              microseconds.
                            example: '2023-01-01T15:00:00.000000000Z'
                        required:
                          - type
                          - value
                        additionalProperties: false
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - date
                            description: The type of the parameter.
                          value:
                            type: string
                            format: date
                            description: A calendar date in the format YYYY-MM-DD.
                            example: '2023-01-01'
                        required:
                          - type
                          - value
                        additionalProperties: false
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - decimal
                            description: The type of the parameter.
                          value:
                            type: string
                            pattern: ^-?\d{1,29}(\.\d{1,9})?$
                            description: >-
                              A decimal number in plain notation, with at most
                              29 digits before and 9 digits after the decimal
                              point.
                            example: '-1234.56'
                        required:
                          - type
                          - value
                        additionalProperties: false
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - list
                            description: The type of the parameter.
                          item_type:
                            type: string
                            enum:
                              - boolean
                              - integer
                              - double
                              - string
                              - timestamp
                              - date
                              - decimal
                            description: The type of every item in the list.
                          value:
                            type: array
                            items: {}
                            maxItems: 100
                            description: >-
                              The items of the list, each a valid value for
                              `item_type`. A maximum of 100 items can be
                              provided.
                            example:
                              - Fundstack
                              - Acme
                        required:
                          - type
                          - item_type
                          - value
                        additionalProperties: false
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - struct
                            description: The type of the parameter.
                          value:
                            type: object
                            description: >-
                              A map of field names to parameter objects, with at
                              least one and a maximum of 25 fields. Names must
                              start with a letter or underscore, only contain
                              letters, digits and underscores, and be at most 64
                              characters long. Structs can contain other
                              structs, up to 2 levels of structs in total.
                            additionalProperties:
                              type: object
                            minProperties: 1
                            maxProperties: 25
                            example:
                              name:
                                type: string
                                value: Fundstack
                        required:
                          - type
                          - value
                        additionalProperties: false
                  description: >-
                    Named parameters referenced in the query using `$name`
                    syntax. A maximum of 25 parameters can be provided. Each
                    parameter must declare its type explicitly. Names must start
                    with a letter or underscore, only contain letters, digits
                    and underscores, and be at most 64 characters long. Compare
                    against a list parameter with `= ANY($name)`, not `IN
                    ($name)`, which does not type check. Read a field of a
                    struct parameter with `get_field($name, 'field')`.
                  maxProperties: 25
                  example:
                    name:
                      type: string
                      value: Fundstack
                    since:
                      type: timestamp
                      value: '2023-01-01T15:00:00.000000000Z'
                    names:
                      type: list
                      item_type: string
                      value:
                        - Fundstack
                        - Acme
              required:
                - sql
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      rows:
                        type: array
                        items:
                          type: object
                          additionalProperties:
                            description: >-
                              A record containing the properties that have been
                              selected in the SQL query.
                            example:
                              record_id: bf071e1f-6035-429d-b874-d83ea64ea13b
                              created_at: '2023-01-01T15:00:00.000000000Z'
                              name: Fundstack
                              created_by:
                                type: workspace-member
                                id: 50cf242c-7fa3-4cad-87d0-75b1af71c57b
                              domains:
                                - fundstack.com
                    required:
                      - rows
                    example:
                      rows:
                        - record_id: bf071e1f-6035-429d-b874-d83ea64ea13b
                          created_at: '2023-01-01T15:00:00.000000000Z'
                          name: Fundstack
                          created_by:
                            type: workspace-member
                            id: 50cf242c-7fa3-4cad-87d0-75b1af71c57b
                          domains:
                            - fundstack.com
                required:
                  - data
                description: Success
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status_code:
                    type: number
                    enum:
                      - 400
                  type:
                    type: string
                    enum:
                      - invalid_request_error
                  code:
                    type: string
                    enum:
                      - filter_error
                  message:
                    type: string
                    example: SQL syntax error.
                required:
                  - status_code
                  - type
                  - code
                  - message
                description: Bad Request
      security:
        - oauth2:
            - record_permission:read
            - object_configuration:read
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: This API uses OAuth 2.0 with the authorization code grant flow.
      flows:
        authorizationCode:
          authorizationUrl: https://app.attio.com/authorize
          tokenUrl: https://app.attio.com/oauth/token
          scopes:
            user_management:read: View workspace members.
            user_management:read-write: View workspace members.
            record_permission:read: View, and optionally write, records.
            record_permission:read-write: View, and optionally write, records.
            object_configuration:read: >-
              View, and optionally write, the configuration and attributes of
              objects.
            object_configuration:read-write: >-
              View, and optionally write, the configuration and attributes of
              objects.
            list_entry:read: View, and optionally write, the entries in a list.
            list_entry:read-write: View, and optionally write, the entries in a list.
            list_configuration:read: >-
              View, and optionally write, the configuration and attributes of
              lists.
            list_configuration:read-write: >-
              View, and optionally write, the configuration and attributes of
              lists.
            public_collection:read: >-
              View, and optionally write, both the settings and information
              within public collections.
            public_collection:read-write: >-
              View, and optionally write, both the settings and information
              within public collections.
            private_collection:read: >-
              View, and optionally modify, both the settings and information of
              all collections within the workspace, regardless of their access
              settings.
            private_collection:read-write: >-
              View, and optionally modify, both the settings and information of
              all collections within the workspace, regardless of their access
              settings.
            comment:read: View comments (and threads), and optionally write comments.
            comment:read-write: View comments (and threads), and optionally write comments.
            task:read: View, and optionally write, tasks.
            task:read-write: View, and optionally write, tasks.
            note:read: View, and optionally write, notes.
            note:read-write: View, and optionally write, notes.
            meeting:read: View, and optionally write, meetings.
            meeting:read-write: View, and optionally write, meetings.
            call_recording:read: >-
              View, and optionally write, call recordings, transcripts and
              speakers for meetings.
            call_recording:read-write: >-
              View, and optionally write, call recordings, transcripts and
              speakers for meetings.
            webhook:read: View, and optionally manage, webhooks.
            webhook:read-write: View, and optionally manage, webhooks.
            file:read: View, and upload files.
            file:read-write: View, and upload files.
            email:read: View email metadata. Email content is never exposed.
            email:read-write: View email metadata. Email content is never exposed.
            activity_configuration:read: >-
              View, and optionally write, the configuration and attributes of
              activities.
            activity_configuration:read-write: >-
              View, and optionally write, the configuration and attributes of
              activities.
            activity_record:read: View, and optionally write, activity records.
            activity_record:read-write: View, and optionally write, activity records.
            sequence_unsubscribe:read: View, and optionally add to, the sequence unsubscribe list.
            sequence_unsubscribe:read-write: View, and optionally add to, the sequence unsubscribe list.
            email_calendar_blocklist:read: >-
              View, and optionally manage, the addresses (email addresses and
              domains) whose emails and calendar events are hidden in Attio.
            email_calendar_blocklist:read-write: >-
              View, and optionally manage, the addresses (email addresses and
              domains) whose emails and calendar events are hidden in Attio.
            view:read: >-
              View, and optionally manage, the saved views of objects and lists,
              with their filters, sorts and shown attributes.
            view:read-write: >-
              View, and optionally manage, the saved views of objects and lists,
              with their filters, sorts and shown attributes.

````

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