Cloudflare updates SQL API introspection: discover JSON fields without guesswork

If an analytics dataset schema contains a JSON column called attributes, but its keys depend on account data, Cloudflare now lets you discover them through introspection. The update, announced on October 27, 2026, added the include_attributes=true parameter: the response lists keys and types found in account data over the preceding seven days.

For developers, this addresses a specific need: before building a filter, they can check which fields actually appear in a selected dataset. The old names include_custom_attributes and custom_attributes still work, but Cloudflare has marked them as deprecated. New integrations should use the updated SQL API introspection.

What introspection returns

Some Cloudflare Analytics datasets store additional key-value pairs in an attributes column. With the new parameter, introspection identifies keys and their types based on seven days of data and returns the information in the dataset object's attributes field. This schema, inferred from recent account records, can help you prepare a SQL query.

In its official example, Cloudflare uses the /client/v4/analytics/sql/introspection endpoint, passes an account identifier and the events.httpRequests dataset name, and enables attribute discovery:

curl --get "https://api.cloudflare.com/client/v4/analytics/sql/introspection" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --data-urlencode "account_tag=$CLOUDFLARE_ACCOUNT_TAG" \
  --data-urlencode "dataset_name=events.httpRequests" \
  --data-urlencode "include_attributes=true"

Before running the command, set the CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_TAG environment variables. The token is passed as bearer credentials; the variable names shown in the example are local command settings, not separate Cloudflare parameters.

From a discovered key to a query

After introspection, check the attributes field in the description of the relevant dataset and choose a key that is actually listed. Cloudflare shows an example of referencing a JSON column key exactly: attributes['http.method']. Use the discovered name in your filter rather than guessing from the event name.

A practical workflow looks like this:

1. Request introspection for the desired dataset with include_attributes=true.
2. Save the keys and types from the returned attributes field along with the date of the check.
3. Build a query using the exact key name, such as attributes['http.method'].
4. Test the query on your account's data, and repeat discovery when the schema or the nature of incoming events changes.

The check date helps with reproducibility: Cloudflare infers attributes from a seven-day window, so the discovered keys reflect recent data rather than an unchanging schema. If a key did not appear during that window, its absence from the result alone does not establish that it is universally unavailable.

How to migrate from the old names

In existing code, replace the include_custom_attributes query parameter with include_attributes, and change response handling from the custom_attributes field to attributes. Cloudflare says the old names continue to work, so you can migrate without urgently restoring an integration.

For a safe transition, check both parts of the contract: the query parameter you send and the response field path you read. Then run the request against the same dataset and compare the list of keys. This test catches a common migration error: the request already uses the new parameter name, but the code still expects the old response field.

Takeaways for analytics pipelines

include_attributes=true makes dynamic JSON fields discoverable through the official introspection mechanism and gives developers types alongside key names. Update new queries and parsers to use include_attributes and the response field attributes, record the discovery date, and build filters from keys that were actually found.