---
title: ShopifyQL with the GraphQL Admin API
description: >-
  Build apps that query analytics data programmatically using the shopifyqlQuery
  endpoint in the GraphQL Admin API.
source_url:
  html: 'https://shopify.dev/docs/apps/build/shopifyql/graphql-admin-api'
  md: 'https://shopify.dev/docs/apps/build/shopifyql/graphql-admin-api.md'
---

ExpandOn this page

* [Required access scopes](https://shopify.dev/docs/apps/build/shopifyql/graphql-admin-api.md#required-access-scopes)
* [API response format](https://shopify.dev/docs/apps/build/shopifyql/graphql-admin-api.md#api-response-format)
* [Rate limiting](https://shopify.dev/docs/apps/build/shopifyql/graphql-admin-api.md#rate-limiting)
* [Next steps](https://shopify.dev/docs/apps/build/shopifyql/graphql-admin-api.md#next-steps)

# ShopifyQL with the GraphQL Admin API

You can send ShopifyQL queries via the GraphQL Admin API, allowing you to build reporting directly into your apps or programmatically extract data for further analysis.

Build apps that query analytics data programmatically using the [`shopifyqlQuery`](https://shopify.dev/docs/api/admin-graphql/latest/queries/shopifyqlQuery) endpoint:

## GraphQL query

```graphql
{
  shopifyqlQuery(
    query: "FROM sales SHOW total_sales, orders SINCE last_week GROUP BY day ORDER BY day DESC"
  ) {
    tableData {
      columns {
        name
        dataType
        displayName
      }
      rows
    }
    parseErrors
  }
}
```

***

## Required access scopes

To use the ShopifyQL API, your app requires the following access scopes:

| Scope | Purpose |
| - | - |
| `read_reports` | Access to analytics and reporting data. |
| `read_customers` | Access to customer data in queries. |
| `read_customer_address` | Access to customer address information. |
| `read_customer_email` | Access to customer email addresses. |
| `read_customer_name` | Access to customer names. |
| `read_customer_phone` | Access to customer phone numbers. |

***

## API response format

The API returns data in a structured JSON format:

## JSON response

```json
{
  "data": {
    "shopifyqlQuery": {
      "tableData": {
        "columns": [
          {
            "name": "day",
            "dataType": "DAY_TIMESTAMP",
            "displayName": "Day"
          },
          {
            "name": "total_sales",
            "dataType": "MONEY",
            "displayName": "Total sales"
          }
        ],
        "rows": [
          { "day": "2024-01-15", "total_sales": "2547.83" },
          { "day": "2024-01-14", "total_sales": "1892.45" }
        ]
      },
      "parseErrors": []
    }
  }
}
```

***

## Rate limiting

The ShopifyQL API uses complexity-based rate limiting rather than fixed queries-per-second. Query complexity is determined by factors including:

* Number of metrics requested
* Number of dimensions in `GROUP BY`
* Date range size
* Use of comparisons and modifiers

***

## Next steps

[GraphQL Admin API reference\
\
](https://shopify.dev/docs/api/admin-graphql/latest/queries/shopifyqlquery)

[API documentation for the `shopifyqlQuery` endpoint.](https://shopify.dev/docs/api/admin-graphql/latest/queries/shopifyqlquery)

[ShopifyQL syntax reference\
\
](https://shopify.dev/docs/api/shopifyql)

[Complete reference for all ShopifyQL keywords, operators, and functions.](https://shopify.dev/docs/api/shopifyql)

***

* [Required access scopes](https://shopify.dev/docs/apps/build/shopifyql/graphql-admin-api.md#required-access-scopes)
* [API response format](https://shopify.dev/docs/apps/build/shopifyql/graphql-admin-api.md#api-response-format)
* [Rate limiting](https://shopify.dev/docs/apps/build/shopifyql/graphql-admin-api.md#rate-limiting)
* [Next steps](https://shopify.dev/docs/apps/build/shopifyql/graphql-admin-api.md#next-steps)