{
  "openapi": "3.0.1",
  "info": {
    "title": "Dataset Aggregate, Group By & Pivot",
    "description": "Returns GROUP BY and pivot tables for any Apify dataset, file or Google Sheet by URL, or JSON array: count, sum, average, min, max, median per group, date buckets, pivot columns. Exports CSV/Excel, appends to a named dataset, posts to a webhook. Agent-ready: pay per event (x402, MCP), per input row.",
    "version": "0.1",
    "x-build-id": "xsFrabo7BYykHpzr8"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/nerolabs~dataset-aggregate-pivot/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-nerolabs-dataset-aggregate-pivot",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/nerolabs~dataset-aggregate-pivot/runs": {
      "post": {
        "operationId": "runs-sync-nerolabs-dataset-aggregate-pivot",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/nerolabs~dataset-aggregate-pivot/run-sync": {
      "post": {
        "operationId": "run-sync-nerolabs-dataset-aggregate-pivot",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "datasetId": {
            "title": "Dataset to aggregate",
            "type": "string",
            "description": "Pick an existing Apify dataset (for example the output of any scraper run). Use this OR 'File URL' OR 'Data (inline)' below. Declaring it this way is what lets this Actor run with limited permissions: it may read the dataset you point at, and nothing else on your account."
          },
          "fileUrl": {
            "title": "File URL (CSV, Excel, JSON or Google Sheet)",
            "type": "string",
            "description": "Instead of a dataset, download the rows to aggregate from a public link: a CSV or TSV file, an Excel .xlsx file (first sheet, header row), a JSON array or JSON Lines file, or a Google Sheet (paste the normal sheet link, sharing set to 'Anyone with the link can view'). The format is detected automatically. Up to 100 MB per run. The download is never charged; only rows processed are. Ignored when 'Dataset to aggregate' is set."
          },
          "data": {
            "title": "Data (inline)",
            "type": "array",
            "description": "A JSON array of records to aggregate, for ad-hoc data instead of a dataset ID or file URL."
          },
          "fileFormat": {
            "title": "File format",
            "enum": [
              "auto",
              "csv",
              "tsv",
              "json",
              "jsonl",
              "xlsx"
            ],
            "type": "string",
            "description": "Only needed if automatic detection gets the file URL's format wrong.",
            "default": "auto"
          },
          "groupByFields": {
            "title": "Group by field(s)",
            "type": "array",
            "description": "One output row per distinct combination of these field values (like SQL GROUP BY). Leave empty to aggregate the whole dataset into a single row. Nested fields work with dot paths, e.g. 'address.city'.",
            "items": {
              "type": "string"
            }
          },
          "aggregations": {
            "title": "Aggregations",
            "type": "array",
            "description": "What to compute per group. Each item: {\"field\": \"amount\", \"function\": \"sum\", \"alias\": \"total_amount\"}. Functions: count (rows, or non-blank values of a field), countDistinct, sum, avg, min, max, median, first, last, list (all values joined by commas), listDistinct. 'alias' is the output column name (optional, defaults to function_field). If empty, a plain row count per group is produced."
          },
          "groupMatching": {
            "title": "Group value matching",
            "enum": [
              "normalized",
              "exact"
            ],
            "type": "string",
            "description": "'Normalized' treats 'South', 'south ' and 'SOUTH' as the same group (case-insensitive, surrounding and repeated whitespace ignored), which is what scraped or hand-entered data usually needs. 'Exact' requires byte-for-byte identical values.",
            "default": "normalized"
          },
          "dateBucketField": {
            "title": "Date bucket field (optional)",
            "type": "string",
            "description": "A date or timestamp field to group by time period, e.g. 'orderedAt' or 'createdAt'. A derived column like 'orderedAt_month' is added to the group-by fields automatically. Accepts ISO dates, most common date strings, and Unix timestamps in seconds or milliseconds."
          },
          "dateBucketGranularity": {
            "title": "Date bucket size",
            "enum": [
              "day",
              "week",
              "month",
              "quarter",
              "year"
            ],
            "type": "string",
            "description": "How to bucket the date field: by calendar day (2026-08-19), ISO week (2026-W34), month (2026-08), quarter (2026-Q3) or year (2026).",
            "default": "month"
          },
          "pivotField": {
            "title": "Pivot field (optional)",
            "type": "string",
            "description": "Turn this field's distinct values into columns, spreadsheet pivot-table style. For example group by 'region' and pivot on 'product' to get one row per region with a 'Widget', 'Gadget', 'Gizmo' column each. Cannot also be a group-by field."
          },
          "pivotValueField": {
            "title": "Pivot value field (optional)",
            "type": "string",
            "description": "The field whose values fill the pivot cells (e.g. 'amount'). Leave empty to fill each pivot cell with a row count."
          },
          "pivotFunction": {
            "title": "Pivot cell function",
            "enum": [
              "count",
              "countDistinct",
              "sum",
              "avg",
              "min",
              "max",
              "median",
              "first",
              "last",
              "list",
              "listDistinct"
            ],
            "type": "string",
            "description": "How to combine the pivot value field within each cell. Ignored (row count used) when no pivot value field is set.",
            "default": "sum"
          },
          "lenientNumbers": {
            "title": "Lenient numbers",
            "type": "boolean",
            "description": "Read numbers stored as text, like '$1,234.50', '49 USD', '12%' or '(300)', as numbers for sum/avg/min/max/median. Scraped prices almost always need this. Turn off to only accept real numbers and plain numeric strings.",
            "default": true
          },
          "sortBy": {
            "title": "Sort by column",
            "type": "string",
            "description": "An output column to sort the groups by: a group-by field, an aggregation alias (e.g. 'total_amount'), or a pivot column. Leave empty to sort by the group-by fields."
          },
          "sortDirection": {
            "title": "Sort direction",
            "enum": [
              "asc",
              "desc"
            ],
            "type": "string",
            "description": "Ascending (A to Z, smallest first) or descending (largest first, e.g. biggest revenue at the top).",
            "default": "asc"
          },
          "topN": {
            "title": "Keep only the top N groups",
            "minimum": 1,
            "type": "integer",
            "description": "After sorting, keep only the first N groups (e.g. top 10 products by revenue). Leave empty to keep all groups. The totals row, if requested, still covers every input row, not just the kept groups."
          },
          "includeTotalsRow": {
            "title": "Add a grand-total row",
            "type": "boolean",
            "description": "Append one extra row aggregating every input row, labelled '(total)' in the first group-by column, with a '_rowType' column marking 'group' vs 'total' rows.",
            "default": false
          },
          "maxItems": {
            "title": "Maximum input rows",
            "minimum": 1,
            "type": "integer",
            "description": "Stop loading after this many rows from the dataset (a cost guard for large datasets). There is a hard safety ceiling of 200,000 rows per run regardless."
          },
          "outputDatasetName": {
            "title": "Also append to a named dataset",
            "type": "string",
            "description": "Optional. A name (3 to 63 letters, digits or hyphens, e.g. 'weekly-sales-summary'). The aggregated rows are appended to a dataset with this name in your account, created on the first run, so a scheduled summary accumulates into one place instead of one dataset per run. Not charged."
          },
          "exportFormats": {
            "title": "Export file formats",
            "uniqueItems": true,
            "type": "array",
            "description": "Also save the result as a real downloadable file in the run's key-value store. CSV opens anywhere; XLSX opens in Excel and Google Sheets with a bold, frozen header row.",
            "items": {
              "type": "string",
              "enum": [
                "csv",
                "xlsx"
              ],
              "enumTitles": [
                "CSV (.csv)",
                "Excel (.xlsx)"
              ]
            }
          },
          "webhookUrl": {
            "title": "Webhook URL (optional)",
            "type": "string",
            "description": "Optional. If set, the aggregated rows (plus download links and the run summary) are POSTed here as JSON the moment this run finishes, so a scheduled GROUP BY lands in Slack, Zapier, Make, n8n or your own endpoint on its own. Only charged when the endpoint actually confirms receipt (HTTP 2xx); a failed delivery is reported as a warning in the run's output and costs nothing."
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}