# Batch aggregate records for analytics dashboards

Runs multiple aggregation requests for dashboard widgets.

Endpoint: POST /api/v2/records/aggregate/batch
Version: 2.0
Security: bearerAuth

## Request fields (application/json):

  - `requests` (array)

  - `requests.xaxis` (object)

  - `requests.xaxis.property` (object)

  - `requests.xaxis.property.object` (string)

  - `requests.xaxis.property.relation` (string)

  - `requests.xaxis.property.propertyName` (string)

  - `requests.xaxis.timeBucket` (string)

  - `requests.xaxis.timeZone` (string)

  - `requests.xaxis.windowDays` (integer)

  - `requests.xaxis.binCount` (integer)

  - `requests.xaxis.metric` (string)

  - `requests.xaxis.label` (string)

  - `requests.yaxis` (object)

  - `requests.yaxis.property` (object)

  - `requests.yaxis.property.object` (string)

  - `requests.yaxis.property.relation` (string)

  - `requests.yaxis.property.propertyName` (string)

  - `requests.yaxis.timeBucket` (string)

  - `requests.yaxis.timeZone` (string)

  - `requests.yaxis.windowDays` (integer)

  - `requests.yaxis.binCount` (integer)

  - `requests.yaxis.metric` (string)

  - `requests.yaxis.label` (string)

  - `requests.id` (string)
    Optional client widget id, echoed in batch responses.

  - `requests.mainObject` (string)

  - `requests.filter` (object)
    DTO representing a filter composed of filter groups for querying records. The filter groups are combined using a logical OR operation. The filter items within each group are combined using a logical AND operation.

  - `requests.filter.groups` (array)
    A collection of filter groups.

  - `requests.filter.groups.items` (object)
    A set of filter items included in the group.

  - `requests.filter.groups.items.object` (string)
    The name of the object to which this pagination item belongs.
    Example: "User"

  - `requests.filter.groups.items.relation` (string)
    The relationship between objects.
    Example: "hasProperty"

  - `requests.filter.groups.items.relationDirection` (string)
    Optional relation direction: outgoing (related→main), incoming (main→related), or omit for undirected.
    Example: "outgoing"

  - `requests.filter.groups.items.property` (string)
    The name of the property within the object.
    Example: "email"

  - `requests.filter.groups.items.relationIncluded` (boolean)
    Specifies whether the relation is included.
    Example: true

  - `requests.filter.groups.items.operator` (string)
    Defines the operator used in the filter. Available operators are defined in the API documentation.
    Example: "EQUALS"

  - `requests.filter.groups.items.value` (any)
    Represents the value to filter against.
    Example: 12345

  - `requests.filter.groups.items.smartContent` (boolean)
    When true, filter fields contain smart content placeholders resolved at runtime.
    Example: true

  - `requests.filter.groups.items.edgeProperty` (boolean)
    When true, propertyName refers to a property stored on the relation edge itself (declared on the relation schema, e.g. partstat on attendees) instead of a property of the related record. Requires relation and propertyName.

  - `requests.query` (string)

  - `requests.xAxis` (object)

  - `requests.xAxis.property` (object)

  - `requests.xAxis.property.object` (string)

  - `requests.xAxis.property.relation` (string)

  - `requests.xAxis.property.propertyName` (string)

  - `requests.xAxis.timeBucket` (string)

  - `requests.xAxis.timeZone` (string)

  - `requests.xAxis.windowDays` (integer)

  - `requests.xAxis.binCount` (integer)

  - `requests.xAxis.metric` (string)

  - `requests.xAxis.label` (string)

  - `requests.yAxis` (object)

  - `requests.yAxis.property` (object)

  - `requests.yAxis.property.object` (string)

  - `requests.yAxis.property.relation` (string)

  - `requests.yAxis.property.propertyName` (string)

  - `requests.yAxis.timeBucket` (string)

  - `requests.yAxis.timeZone` (string)

  - `requests.yAxis.windowDays` (integer)

  - `requests.yAxis.binCount` (integer)

  - `requests.yAxis.metric` (string)

  - `requests.yAxis.label` (string)

  - `requests.series` (object)

  - `requests.series.groupBy` (object)

  - `requests.series.groupBy.object` (string)

  - `requests.series.groupBy.relation` (string)

  - `requests.series.groupBy.propertyName` (string)

  - `requests.limit` (integer)
    Optional top-N series limit. For additive metrics (count, countDistinct, sum), keeps the N series with the highest total Y. Null or <= 0 means no truncation.

  - `requests.sort` (string)

  - `requests.excludeEmptyValues` (boolean)
    When true, omit null/blank/(empty) category buckets from the response. Useful for bar and pie charts grouped by optional properties.

## Response 200 fields (application/json):

  - `message` (string)
    Example: "Success"

  - `data` (array)

## Response 400 fields (application/json):

  - `message` (string)
    The error message providing details about the failure.
    Example: "Resource not found."

  - `errors` (array)
    A list of error types providing further details about the error.

  - `errors.message` (string, required)
    The error message providing details about the failure.
    Example: "Invalid file type."

  - `errors.type` (string, required)
    The type of error.
    Enum: "VALIDATION", "NOT_FOUND", "TEST", "RELATION_NOT_ALLOWED", "INVALID_VALUE", "GENERAL", "INVALID_FILE_TYPE", "INTERNAL_SERVER_ERROR", "CARAER_ERROR", "INVALID_EMAIL", "INVALID_DATE"

  - `errors.correctionSuggestion` (string, required)
    A suggestion on how to correct the error.
    Example: "Try uploading a different file type."

  - `status` (integer)
    The HTTP status code associated with the error.
    Example: 400

  - `stackTrace` (string)

  - `roles` (array)
    Roles the caller is missing when the failure is an authorization error.
    Enum: "USER", "ADMIN", "RESELLER", "DEVELOPER", "SUPER_ADMIN"

  - `scopes` (array)
    Scopes the caller is missing when the failure is an authorization error.

  - `requestId` (string)
    Request correlation ID for support and log tracing.
    Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

## Response 401 fields (application/json):

  - `message` (string)
    The error message providing details about the failure.
    Example: "Resource not found."

  - `errors` (array)
    A list of error types providing further details about the error.

  - `errors.message` (string, required)
    The error message providing details about the failure.
    Example: "Invalid file type."

  - `errors.type` (string, required)
    The type of error.
    Enum: "VALIDATION", "NOT_FOUND", "TEST", "RELATION_NOT_ALLOWED", "INVALID_VALUE", "GENERAL", "INVALID_FILE_TYPE", "INTERNAL_SERVER_ERROR", "CARAER_ERROR", "INVALID_EMAIL", "INVALID_DATE"

  - `errors.correctionSuggestion` (string, required)
    A suggestion on how to correct the error.
    Example: "Try uploading a different file type."

  - `status` (integer)
    The HTTP status code associated with the error.
    Example: 400

  - `stackTrace` (string)

  - `roles` (array)
    Roles the caller is missing when the failure is an authorization error.
    Enum: "USER", "ADMIN", "RESELLER", "DEVELOPER", "SUPER_ADMIN"

  - `scopes` (array)
    Scopes the caller is missing when the failure is an authorization error.

  - `requestId` (string)
    Request correlation ID for support and log tracing.
    Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

## Response 403 fields (application/json):

  - `message` (string)
    The error message providing details about the failure.
    Example: "Resource not found."

  - `errors` (array)
    A list of error types providing further details about the error.

  - `errors.message` (string, required)
    The error message providing details about the failure.
    Example: "Invalid file type."

  - `errors.type` (string, required)
    The type of error.
    Enum: "VALIDATION", "NOT_FOUND", "TEST", "RELATION_NOT_ALLOWED", "INVALID_VALUE", "GENERAL", "INVALID_FILE_TYPE", "INTERNAL_SERVER_ERROR", "CARAER_ERROR", "INVALID_EMAIL", "INVALID_DATE"

  - `errors.correctionSuggestion` (string, required)
    A suggestion on how to correct the error.
    Example: "Try uploading a different file type."

  - `status` (integer)
    The HTTP status code associated with the error.
    Example: 400

  - `stackTrace` (string)

  - `roles` (array)
    Roles the caller is missing when the failure is an authorization error.
    Enum: "USER", "ADMIN", "RESELLER", "DEVELOPER", "SUPER_ADMIN"

  - `scopes` (array)
    Scopes the caller is missing when the failure is an authorization error.

  - `requestId` (string)
    Request correlation ID for support and log tracing.
    Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

## Response 404 fields (application/json):

  - `message` (string)
    The error message providing details about the failure.
    Example: "Resource not found."

  - `errors` (array)
    A list of error types providing further details about the error.

  - `errors.message` (string, required)
    The error message providing details about the failure.
    Example: "Invalid file type."

  - `errors.type` (string, required)
    The type of error.
    Enum: "VALIDATION", "NOT_FOUND", "TEST", "RELATION_NOT_ALLOWED", "INVALID_VALUE", "GENERAL", "INVALID_FILE_TYPE", "INTERNAL_SERVER_ERROR", "CARAER_ERROR", "INVALID_EMAIL", "INVALID_DATE"

  - `errors.correctionSuggestion` (string, required)
    A suggestion on how to correct the error.
    Example: "Try uploading a different file type."

  - `status` (integer)
    The HTTP status code associated with the error.
    Example: 400

  - `stackTrace` (string)

  - `roles` (array)
    Roles the caller is missing when the failure is an authorization error.
    Enum: "USER", "ADMIN", "RESELLER", "DEVELOPER", "SUPER_ADMIN"

  - `scopes` (array)
    Scopes the caller is missing when the failure is an authorization error.

  - `requestId` (string)
    Request correlation ID for support and log tracing.
    Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

## Response 500 fields (application/json):

  - `message` (string)
    The error message providing details about the failure.
    Example: "Resource not found."

  - `errors` (array)
    A list of error types providing further details about the error.

  - `errors.message` (string, required)
    The error message providing details about the failure.
    Example: "Invalid file type."

  - `errors.type` (string, required)
    The type of error.
    Enum: "VALIDATION", "NOT_FOUND", "TEST", "RELATION_NOT_ALLOWED", "INVALID_VALUE", "GENERAL", "INVALID_FILE_TYPE", "INTERNAL_SERVER_ERROR", "CARAER_ERROR", "INVALID_EMAIL", "INVALID_DATE"

  - `errors.correctionSuggestion` (string, required)
    A suggestion on how to correct the error.
    Example: "Try uploading a different file type."

  - `status` (integer)
    The HTTP status code associated with the error.
    Example: 400

  - `stackTrace` (string)

  - `roles` (array)
    Roles the caller is missing when the failure is an authorization error.
    Enum: "USER", "ADMIN", "RESELLER", "DEVELOPER", "SUPER_ADMIN"

  - `scopes` (array)
    Scopes the caller is missing when the failure is an authorization error.

  - `requestId` (string)
    Request correlation ID for support and log tracing.
    Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"