--- title: Query analytics top-N --- [Skip to content](#%5Ftop) [API Reference](https://developers.cloudflare.com/api/python) [Analytics Query](https://developers.cloudflare.com/api/python/resources/analytics%5Fquery) Copy Markdown Open in **Claude** Open in **ChatGPT** Open in **Cursor** --- **Copy Markdown** **View as Markdown** # Query analytics top-N analytics\_query.top\_n(strdataset, AnalyticsQueryTopNParams\*\*kwargs) \-> SyncSinglePage\[[AnalyticsQueryTopNResponse](https://developers.cloudflare.com/api/python/resources/analytics%5Fquery#%28resource%29%20analytics%5Fquery%20%3E%20%28model%29%20analytics%5Fquery%5Ftop%5Fn%5Fresponse%20%3E%20%28schema%29)\] POST/accounts/{account\_id}/analytics/query/{dataset}/top-n Returns the top N results for a dataset by a specified stat. Includes an array of result rows, each containing the requested stats and group-by dimensions. ##### Security API Token The preferred authorization scheme for interacting with the Cloudflare API. [Create a token](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/). **Example:**`Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY` API Email + API Key The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key. **Example:**`X-Auth-Email: user@example.com` The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys. **Example:**`X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194` ##### Accepted Permissions (at least one required) `Zero Trust Read` ##### ParametersExpand Collapse account\_id: str maxLength32 dataset: str filters: Iterable\[Filter\] Filters to apply before aggregating results. name: str Specifies the column name to filter on. Requires a valid column for the target dataset (e.g. `country`, `allowed`, `appId`). op: str Filter operator. Common values: `eq`, `neq`, `in`, `not_in`, `gt`, `lt`, `gte`, `lte`. values: Sequence\[Union\[str, bool, float\]\] Values to match against. Type depends on the column. One of the following: str bool float from\_: Union\[str, datetime\] The start of the query time range (inclusive). RFC3339 format with timezone is required (e.g. `2024-11-05T00:00:00Z`). formatdate-time group\_by: Sequence\[str\] Specifies the column names to group results by. Requires valid columns for the target dataset. n: int Maximum number of results to return. formatint64 minimum1 order\_by: str Specifies the stat name for sorting results in descending order. Requires a valid stat for the target dataset. stats: Sequence\[str\] Specifies the stat names to include in results. Requires valid stats for the target dataset (e.g. `attemptsTotal`, `bytesTotal`). to: Union\[str, datetime\] Specifies the end of the query time range (exclusive). Requires RFC3339 format with timezone. formatdate-time ##### ReturnsExpand Collapse Dict\[str, object\] Maps field names to values. Keys represent stat names and group-by column names. Values depend on the dataset (strings, numbers, booleans). ### Query analytics top-N Python HTTPHTTP TypeScriptTypeScript PythonPython GoGo TerraformTerraform ``` import os from datetime import datetime from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) page = client.analytics_query.top_n( dataset="gateway-http", account_id="023e105f4ecef8ad9ca31a8372d0c353", filters=[], from_=datetime.fromisoformat("2024-11-05T00:00:00"), group_by=["appName", "appCategory"], n=10, order_by="bytesTotal", stats=["bytesTotal", "requestsTotal"], to=datetime.fromisoformat("2024-11-06T00:00:00"), ) page = page.result[0] print(page) ``` 200 example 400 example 400 example 401 example 403 example 403 example ``` { "errors": [], "messages": [ { "code": 1000, "message": "API in beta: expect breaking changes." } ], "result": [ { "appCategory": "Collaboration", "appName": "Slack", "bytesTotal": 10485760, "requestsTotal": 1024 }, { "appCategory": "File Storage", "appName": "Dropbox", "bytesTotal": 5242880, "requestsTotal": 512 } ], "success": true } ``` ``` { "errors": [ { "code": 11005, "message": "art.api.parameter.invalid" } ], "messages": [ { "code": 1002, "message": "Parameter 'from' has invalid value '2024-11-05 00:00:00'. Should be of type: 'RFC3339'" } ], "result": null, "success": false } ``` ``` { "errors": [ { "code": 11005, "message": "art.api.parameter.invalid" } ], "messages": [ { "code": 1000, "message": "API in beta: expect breaking changes." } ], "result": null, "success": false } ``` ``` { "errors": [ { "code": 11003, "message": "art.api.resource.insufficient_permissions" } ], "messages": [], "result": null, "success": false } ``` ``` { "errors": [ { "code": 11003, "message": "art.api.resource.insufficient_permissions" } ], "messages": [], "result": null, "success": false } ``` ``` { "errors": [ { "code": 11003, "message": "art.api.resource.insufficient_permissions" } ], "messages": [], "result": null, "success": false } ``` ##### Returns Examples 200 example 400 example 400 example 401 example 403 example 403 example ``` { "errors": [], "messages": [ { "code": 1000, "message": "API in beta: expect breaking changes." } ], "result": [ { "appCategory": "Collaboration", "appName": "Slack", "bytesTotal": 10485760, "requestsTotal": 1024 }, { "appCategory": "File Storage", "appName": "Dropbox", "bytesTotal": 5242880, "requestsTotal": 512 } ], "success": true } ``` ``` { "errors": [ { "code": 11005, "message": "art.api.parameter.invalid" } ], "messages": [ { "code": 1002, "message": "Parameter 'from' has invalid value '2024-11-05 00:00:00'. Should be of type: 'RFC3339'" } ], "result": null, "success": false } ``` ``` { "errors": [ { "code": 11005, "message": "art.api.parameter.invalid" } ], "messages": [ { "code": 1000, "message": "API in beta: expect breaking changes." } ], "result": null, "success": false } ``` ``` { "errors": [ { "code": 11003, "message": "art.api.resource.insufficient_permissions" } ], "messages": [], "result": null, "success": false } ``` ``` { "errors": [ { "code": 11003, "message": "art.api.resource.insufficient_permissions" } ], "messages": [], "result": null, "success": false } ``` ``` { "errors": [ { "code": 11003, "message": "art.api.resource.insufficient_permissions" } ], "messages": [], "result": null, "success": false } ```