{
  "openapi": "3.0.1",
  "info": {
    "title": "Dataset Aggregate, Group By & Pivot",
    "description": "Returns GROUP BY and pivot tables for any Apify dataset or JSON array: count, sum, average, min, max, median per group, date buckets, plus CSV or Excel export. Inputs: dataset ID or inline data, group-by fields, aggregations. Agent-ready: pay per event (x402 and MCP), per input row and file.",
    "version": "0.1",
    "x-build-id": "RL3BwNG9yATq1WpGT"
  },
  "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 'Data (inline)' below, not both. 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."
          },
          "data": {
            "title": "Data (inline)",
            "type": "array",
            "description": "A JSON array of records to aggregate, for ad-hoc data instead of a dataset ID."
          },
          "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
          },
          "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)"
              ]
            }
          },
          "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."
          }
        }
      },
      "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
                  }
                }
              },
              "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}