---
title: About the GraphQL Admin API
description: >-
  Run ShopifyQL queries from your app with the GraphQL Admin API. Send a query
  through the shopifyqlQuery field, read the structured results, and render them
  in your own UI.
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'
api_name: shopifyql
---

# About the Graph​QL Admin API

The GraphQL Admin API runs a ShopifyQL query from your app. You send a [ShopifyQL](https://shopify.dev/docs/api/shopifyql) query as a string through the [`shopifyqlQuery`](https://shopify.dev/docs/api/admin-graphql/latest/queries/shopifyqlQuery) field and get back structured results to render on a dashboard or in an email. Use it when you're building an app and want store analytics inside it, such as a total, a trend, or a ranking across many records. To read or change a single order, customer, or product, query the GraphQL Admin API objects directly instead. It's the same query language you prototype in the Shopify admin, running unchanged from code.

***

## How it works

A query names a dataset and the metrics to return with [`FROM` and `SHOW`](https://shopify.dev/docs/api/shopifyql/latest/syntax/from-and-show). Your app sends it through the `shopifyqlQuery` field and reads back a `tableData` response of typed columns and rows. The response is rendering-agnostic, so the same columns and rows can drive a table, a chart, or a single headline metric.

## GraphQL query

```graphql
{
  shopifyqlQuery(
    query: "FROM sales SHOW total_sales, orders TIMESERIES day SINCE -7d ORDER BY day ASC"
  ) {
    tableData {
      columns {
        name
        dataType
        displayName
      }
      rows
    }
    parseErrors
  }
}
```

Running `shopifyqlQuery` requires the [`read_reports`](https://shopify.dev/docs/api/usage/access-scopes#authenticated-access-scopes) access scope, [Level 2 access to protected customer data](https://shopify.dev/docs/apps/launch/protected-customer-data), and GraphQL Admin API version `2025-10` or higher. Protected customer data approval can take time, so request it early.

***

## Developer tools and resources

[Handle errors and budgets\
\
](https://shopify.dev/docs/apps/build/shopifyql/graphql-admin-api/errors-limits-and-performance)

[Handle failed queries, stay within complexity-based rate limits, and account for data that isn't real time.](https://shopify.dev/docs/apps/build/shopifyql/graphql-admin-api/errors-limits-and-performance)

[Segment query language\
\
](https://shopify.dev/docs/apps/build/shopifyql/segment-query-language-reference)

[Query segments of customers with ShopifyQL.](https://shopify.dev/docs/apps/build/shopifyql/segment-query-language-reference)

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

[Browse every dataset, metric, dimension, and clause in the language.](https://shopify.dev/docs/api/shopifyql)

[Sales dashboard example app on GitHub\
\
](https://github.com/Shopify/example-shopifyql--sales-dashboard--react)

[The complete embedded React app from the tutorial, querying `shopifyqlQuery` and rendering the results in its UI.](https://github.com/Shopify/example-shopifyql--sales-dashboard--react)

***

## Get started

[Build a sales dashboard with the GraphQL Admin API\
\
](https://shopify.dev/docs/apps/build/shopifyql/graphql-admin-api/build-a-sales-dashboard)

[Build an embedded app that sends a query through `shopifyqlQuery`, reads the structured results, and renders them in its UI.](https://shopify.dev/docs/apps/build/shopifyql/graphql-admin-api/build-a-sales-dashboard)

***