Skip to content

SQL API

Last updated View as MarkdownAgent setup

The Workers Analytics Engine SQL API is an HTTP API that allows executing SQL queries against your Workers Analytics Engine datasets.

The API is hosted at https://api.cloudflare.com/client/v4/accounts/<account_id>/analytics_engine/sql.

Authentication

Authentication is done via bearer token. An Authorization: Bearer <token> header must be supplied with every request to the API.

Use the dashboard to create a token with permission to read analytics data on your account:

  1. Visit the API tokens ↗ page in the Cloudflare dashboard.
  2. Select Create Token.
  3. Select Create Custom Token.
  4. Complete the Create Custom Token form as follows:
    • Give your token a descriptive name.
    • For Permissions select Account | Account Analytics | Read
    • Optionally configure account and IP restrictions and TTL.
    • Submit and confirm the form to create the token.
  5. Make a note of the token string.

Querying the API

Submit the query text in the body of a POST request to the API address. The format of the data returned can be selected using the FORMAT option in your query.

You can use cURL to test the API as follows, replacing the <account_id> with your 32 character account ID (available in the dashboard) and the <token> with the token string you generated above.

curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/analytics_engine/sql" \
--header "Authorization: Bearer <API_TOKEN>" \
--data "SELECT 'Hello Workers Analytics Engine' AS message"

If you have already published some data, you might try executing the following to confirm that the dataset has been created in the DB.

curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/analytics_engine/sql" \
--header "Authorization: Bearer <API_TOKEN>" \
--data "SHOW TABLES"

Refer to the Workers Analytics Engine