# Analytics Query ## Query analytics summary `analytics_query.summary(strdataset, AnalyticsQuerySummaryParams**kwargs) -> AnalyticsQuerySummaryResponse` **post** `/accounts/{account_id}/analytics/query/{dataset}/summary` Returns aggregate summary stats for a dataset. Includes current-period and previous-period totals for trend comparison. ### Parameters - `account_id: str` - `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. - `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`). - `group_by: Sequence[str]` Specifies the column names to group results by. Requires valid columns 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. ### Returns - `class AnalyticsQuerySummaryResponse: …` - `current_total: List[Dict[str, object]]` Aggregated stats for the requested time range. - `previous_total: List[Dict[str, object]]` Aggregated stats for the equivalent preceding time range, for trend comparison. ### Example ```python 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 ) response = client.analytics_query.summary( dataset="access-logins", account_id="023e105f4ecef8ad9ca31a8372d0c353", filters=[], from_=datetime.fromisoformat("2024-11-01T00:00:00"), group_by=[], stats=["attemptsTotal"], to=datetime.fromisoformat("2024-11-08T00:00:00"), ) print(response.current_total) ``` #### Response ```json { "errors": [], "messages": [ { "code": 1000, "message": "API in beta: expect breaking changes." } ], "result": { "currentTotal": [ { "attemptsTotal": 48291 } ], "previousTotal": [ { "attemptsTotal": 41033 } ] }, "success": true } ``` ## Query analytics timeseries `analytics_query.timeseries(strdataset, AnalyticsQueryTimeseriesParams**kwargs) -> AnalyticsQueryTimeseriesResponse` **post** `/accounts/{account_id}/analytics/query/{dataset}/timeseries` Returns time-bucketed analytics data for a dataset. Includes time slots, each containing the requested stats, group-by dimensions, and resolution-controlled bucket size (e.g. `hour`, `day`). ### Parameters - `account_id: str` - `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. - `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`). - `group_by: Sequence[str]` Specifies the column names to group results by. Requires valid columns for the target dataset. - `resolution: str` Time bucket size for grouping results. Controls the granularity of the returned time slots. - `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. ### Returns - `class AnalyticsQueryTimeseriesResponse: …` - `resolution: str` The resolution used for time bucketing. - `slots: List[Dict[str, object]]` Time-bucketed result rows. Each slot contains a `time_bucket` field plus the requested stats and group-by dimensions. ### Example ```python 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 ) response = client.analytics_query.timeseries( dataset="shadow_it", account_id="023e105f4ecef8ad9ca31a8372d0c353", filters=[{ "name": "allowed", "op": "eq", "values": [True], }], from_=datetime.fromisoformat("2024-11-01T00:00:00"), group_by=["country", "allowed"], resolution="day", stats=["attemptsTotal"], to=datetime.fromisoformat("2024-11-08T00:00:00"), ) print(response.resolution) ``` #### Response ```json { "errors": [], "messages": [ { "code": 1000, "message": "API in beta: expect breaking changes." } ], "result": { "resolution": "hour", "slots": [ { "appName": "Slack", "bytesTotal": 1048576, "time_bucket": "2024-11-05T00:00:00Z" }, { "appName": "Slack", "bytesTotal": 2097152, "time_bucket": "2024-11-05T01:00:00Z" } ] }, "success": true } ``` ## Query analytics top-N `analytics_query.top_n(strdataset, AnalyticsQueryTopNParams**kwargs) -> SyncSinglePage[AnalyticsQueryTopNResponse]` **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. ### Parameters - `account_id: str` - `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. - `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`). - `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. - `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. ### Returns - `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). ### Example ```python 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) ``` #### Response ```json { "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 } ``` ## Domain Types ### Analytics Query Summary Response - `class AnalyticsQuerySummaryResponse: …` - `current_total: List[Dict[str, object]]` Aggregated stats for the requested time range. - `previous_total: List[Dict[str, object]]` Aggregated stats for the equivalent preceding time range, for trend comparison. ### Analytics Query Timeseries Response - `class AnalyticsQueryTimeseriesResponse: …` - `resolution: str` The resolution used for time bucketing. - `slots: List[Dict[str, object]]` Time-bucketed result rows. Each slot contains a `time_bucket` field plus the requested stats and group-by dimensions. ### Analytics Query Top N Response - `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). # Data Security # Content Findings ## Top integrations by content findings `analytics_query.data_security.content_findings.top_n(ContentFindingTopNParams**kwargs) -> SyncSinglePage[ContentFindingTopNResponse]` **post** `/accounts/{account_id}/analytics/query/data-security/content-findings/top-n` Returns the top N integrations ranked by total content findings. ### Parameters - `account_id: str` - `filters: Iterable[Filter]` Filters to apply. `findingType = content` is applied automatically for CASB data. - `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. - `str` - `bool` - `float` - `from_: Union[str, datetime]` Start of the query time range (inclusive). RFC3339. - `n: int` Maximum number of integrations to return. - `to: Union[str, datetime]` End of the query time range (exclusive). RFC3339. ### Returns - `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). ### Example ```python 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.data_security.content_findings.top_n( account_id="023e105f4ecef8ad9ca31a8372d0c353", filters=[], from_=datetime.fromisoformat("2024-11-01T00:00:00"), n=10, to=datetime.fromisoformat("2024-11-08T00:00:00"), ) page = page.result[0] print(page) ``` #### Response ```json { "errors": [], "messages": [ { "code": 1000, "message": "API in beta: expect breaking changes." } ], "result": [ { "integrationId": "123e4567-e89b-12d3-a456-426614174000", "integrationName": "Google Workspace", "total": 42 }, { "integrationId": "223e4567-e89b-12d3-a456-426614174001", "integrationName": "Microsoft 365", "total": 17 } ], "success": true } ``` ## Domain Types ### Content Finding Top N Response - `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). # Findings ## Data security findings summary `analytics_query.data_security.findings.summary(FindingSummaryParams**kwargs) -> FindingSummaryResponse` **post** `/accounts/{account_id}/analytics/query/data-security/findings/summary` Returns aggregate current-period and previous-period totals for CASB findings. ### Parameters - `account_id: str` - `filters: Iterable[Filter]` Filters to apply. - `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. - `str` - `bool` - `float` - `from_: Union[str, datetime]` Start of the query time range (inclusive). RFC3339. - `to: Union[str, datetime]` End of the query time range (exclusive). RFC3339. ### Returns - `class FindingSummaryResponse: …` - `current_total: List[Dict[str, object]]` Aggregated stats for the requested time range. - `previous_total: List[Dict[str, object]]` Aggregated stats for the equivalent preceding time range, for trend comparison. ### Example ```python 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 ) response = client.analytics_query.data_security.findings.summary( account_id="023e105f4ecef8ad9ca31a8372d0c353", filters=[], from_=datetime.fromisoformat("2024-11-01T00:00:00"), to=datetime.fromisoformat("2024-11-08T00:00:00"), ) print(response.current_total) ``` #### Response ```json { "errors": [], "messages": [ { "code": 1000, "message": "API in beta: expect breaking changes." } ], "result": { "currentTotal": [ { "findingProduct": "Cloud", "findingType": "Content", "findingsTotal": 48291 }, { "findingProduct": "SaaS", "findingType": "Posture", "findingsTotal": 1205 } ], "previousTotal": [ { "findingProduct": "Cloud", "findingType": "Content", "findingsTotal": 41033 }, { "findingProduct": "SaaS", "findingType": "Posture", "findingsTotal": 982 } ] }, "success": true } ``` ## Data security findings timeseries `analytics_query.data_security.findings.timeseries(FindingTimeseriesParams**kwargs) -> FindingTimeseriesResponse` **post** `/accounts/{account_id}/analytics/query/data-security/findings/timeseries` Returns merged time-bucketed CASB findings. ### Parameters - `account_id: str` - `filters: Iterable[Filter]` Filters to apply. - `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. - `str` - `bool` - `float` - `from_: Union[str, datetime]` Start of the query time range (inclusive). RFC3339. - `to: Union[str, datetime]` End of the query time range (exclusive). RFC3339. ### Returns - `class FindingTimeseriesResponse: …` Merged CASB and CDE findings timeseries result. - `slots: List[Dict[str, object]]` Contains time-bucketed result rows. Each slot includes a `timestamp` plus `content` and `posture` maps with `cloud` and `saas` keys. - `resolution: Optional[str]` Always null for this endpoint. ### Example ```python 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 ) response = client.analytics_query.data_security.findings.timeseries( account_id="023e105f4ecef8ad9ca31a8372d0c353", filters=[], from_=datetime.fromisoformat("2024-11-01T00:00:00"), to=datetime.fromisoformat("2024-11-08T00:00:00"), ) print(response.slots) ``` #### Response ```json { "errors": [], "messages": [ { "code": 1000, "message": "API in beta: expect breaking changes." } ], "result": { "slots": [ { "content": { "cloud": 150, "saas": 23 }, "posture": { "cloud": 0, "saas": 5 }, "timestamp": "2024-11-05T00:00:00Z" }, { "content": { "cloud": 180, "saas": 30 }, "posture": { "cloud": 0, "saas": 7 }, "timestamp": "2024-11-06T00:00:00Z" } ] }, "success": true } ``` ## Domain Types ### Finding Summary Response - `class FindingSummaryResponse: …` - `current_total: List[Dict[str, object]]` Aggregated stats for the requested time range. - `previous_total: List[Dict[str, object]]` Aggregated stats for the equivalent preceding time range, for trend comparison. ### Finding Timeseries Response - `class FindingTimeseriesResponse: …` Merged CASB and CDE findings timeseries result. - `slots: List[Dict[str, object]]` Contains time-bucketed result rows. Each slot includes a `timestamp` plus `content` and `posture` maps with `cloud` and `saas` keys. - `resolution: Optional[str]` Always null for this endpoint.