Reporting API

Keywords

Here's an example curl call that returns data for each keyword. Here is a list of template tokens to swap out:

• apiKey: create your own from Settings → Users → Create API Token — see How do I create an API token?
• workspaceId: Nozzle workspace id
• teamId: Nozzle project id, which used to be called teams
• start: start of the reporting time range
• end: end of the reporting time range
• brandIds: choose a single brand id (copy from brand manager)
• segmentIds: choose a single segment id (copy from segment manager)
• keywordGroups: choose a single keyword group, exact match and case-sensitive
• keywordIds: to limit to just the provided keywords, add an array of keyword ids

workspaceId and teamId go in the JSON body as plain numbers, with no quotes around them. Sending them as HTTP headers instead doesn't work. Leave either one out and the call returns 400 naming the missing field. teamId must be a project in that workspace; a project ID from another workspace returns 404. See What do common API errors mean? for both.

brandIds can be swapped out for brandTypes, brandProperties, brandIds, domainIds or urlIds, as long as you also change rollupBy to match.

Metrics

The example lists all the available metrics and aggregations, you can slim down the response by eliminating variations you don't need.

curl -X POST --location "https://api.nozzle.app/reports/groupByOverTime" \
    -H "accept: application/json, text/plain, */*" \
    -H "authorization: Token {{apiKey}}" \
    -H "Content-Type: application/json" \
    -d '{
          "workspaceId":{{workspaceId}},
          "teamId":{{teamId}},
          "start": "2026-02-03T00:00:00+00:00",
          "end": "2026-03-04T23:59:59+00:00",
          "rollupBy": "brand_id",
          "groupBy": "keyword_id",
          "samples": 1,
          "filters": {
            "segmentIds": [
              1
            ],
            "keywordGroups": [
              "- All Keywords -"
            ],
            "brandIds": [
              971604420480256
            ],
            "brandProperties": [],
            "brandTypes": [],
            "domainIds": [],
            "urlIds": [],
            "keywordIds": []
          },
          "orderBy": [
            {
              "metric": {
                "id": "percentage_of_viewport",
                "aggregation": "avg",
                "subAggregation": "total",
                "postAggregation": "value"
              },
              "limit": 50,
              "offset": 0,
              "desc": true
            }
          ],
          "includedMetrics": [
            {
              "id": "percentage_of_viewport",
              "aggregation": "avg",
              "subAggregation": "total",
              "postAggregation": "value"
            },
            {
              "id": "top_rank",
              "aggregation": "avg",
              "subAggregation": "total",
              "postAggregation": "value"
            },
            {
              "id": "top_stat_base_rank",
              "aggregation": "avg",
              "subAggregation": "total",
              "postAggregation": "value"
            },
            {
              "id": "estimated_traffic_sov",
              "aggregation": "sum",
              "subAggregation": "total",
              "postAggregation": "value"
            },
            {
              "id": "click_through_rate",
              "aggregation": "avg",
              "subAggregation": "total",
              "postAggregation": "value"
            },
            {
              "id": "estimated_traffic",
              "aggregation": "sum",
              "subAggregation": "total",
              "postAggregation": "value"
            },
            {
              "id": "top_pixels_from_top",
              "aggregation": "avg",
              "subAggregation": "total",
              "postAggregation": "value"
            },
            {
              "id": "percentage_of_viewport",
              "aggregation": "avg",
              "subAggregation": "total",
              "postAggregation": "value"
            },
            {
              "id": "percentage_of_dom",
              "aggregation": "avg",
              "subAggregation": "total",
              "postAggregation": "value"
            },
            {
              "id": "results",
              "aggregation": "count",
              "subAggregation": "total",
              "postAggregation": "value"
            },
            {
              "id": "unique_urls",
              "aggregation": "count",
              "subAggregation": "total",
              "postAggregation": "value"
            },
            {
              "id": "ppc_value",
              "aggregation": "sum",
              "subAggregation": "total",
              "postAggregation": "value"
            },
            {
              "id": "adwords_search_volume",
              "aggregation": "sum",
              "subAggregation": "total",
              "postAggregation": "value"
            },
            {
              "id": "top_ranking_results",
              "aggregation": "any",
              "subAggregation": "any",
              "postAggregation": "value"
            },
            {
              "id": "top_rank",
              "aggregation": "avg",
              "subAggregation": "total",
              "postAggregation": "change"
            },
            {
              "id": "top_stat_base_rank",
              "aggregation": "avg",
              "subAggregation": "total",
              "postAggregation": "change"
            },
            {
              "id": "estimated_traffic_sov",
              "aggregation": "sum",
              "subAggregation": "total",
              "postAggregation": "change"
            },
            {
              "id": "click_through_rate",
              "aggregation": "avg",
              "subAggregation": "total",
              "postAggregation": "change"
            },
            {
              "id": "estimated_traffic",
              "aggregation": "sum",
              "subAggregation": "total",
              "postAggregation": "change"
            },
            {
              "id": "top_pixels_from_top",
              "aggregation": "avg",
              "subAggregation": "total",
              "postAggregation": "change"
            },
            {
              "id": "percentage_of_viewport",
              "aggregation": "avg",
              "subAggregation": "total",
              "postAggregation": "change"
            },
            {
              "id": "percentage_of_dom",
              "aggregation": "avg",
              "subAggregation": "total",
              "postAggregation": "change"
            },
            {
              "id": "results",
              "aggregation": "count",
              "subAggregation": "total",
              "postAggregation": "change"
            },
            {
              "id": "unique_urls",
              "aggregation": "count",
              "subAggregation": "total",
              "postAggregation": "change"
            },
            {
              "id": "ppc_value",
              "aggregation": "sum",
              "subAggregation": "total",
              "postAggregation": "change"
            },
            {
              "id": "adwords_search_volume",
              "aggregation": "sum",
              "subAggregation": "total",
              "postAggregation": "change"
            }
          ]
        }'