---
title: "Aggregate events"
method: POST
path: "/api/v2/logs/analytics/aggregate"
tags: ["Logs"]
---

# Aggregate events

`POST /api/v2/logs/analytics/aggregate`

The API endpoint to aggregate events into buckets and compute metrics and timeseries.

## Request body

- LogsAggregateRequest — The object sent with the request to retrieve a list of logs from your organization.
  - `compute` LogsCompute[] — The list of metrics or timeseries to compute for the retrieved buckets.
    - `aggregation` 'count' | 'cardinality' | 'pc75' | 'pc90' | 'pc95' | 'pc98' | 'pc99' | 'sum' | 'min' | 'max' | 'avg' | 'median', required — An aggregation function
    - `interval` string — The time buckets' size (only used for type=timeseries) Defaults to a resolution of 150 points
    - `metric` string — The metric to use
    - `type` 'timeseries' | 'total' — The type of compute
  - `filter` LogsQueryFilter — The search and filter query settings
    - `from` string — The minimum time for the requested logs, supports date math and regular timestamps (milliseconds).
    - `indexes` string[] — For customers with multiple indexes, the indexes to search. Defaults to ['*'] which means all indexes.
    - `query` string — The search query - following the log search syntax.
    - `storage_tier` 'indexes' | 'online-archives' | 'flex' — Specifies storage type as indexes, online-archives or flex
    - `to` string — The maximum time for the requested logs, supports date math and regular timestamps (milliseconds).
  - `group_by` LogsGroupBy[] — The rules for the group by
    - `facet` string, required — The name of the facet to use (required)
    - `histogram` LogsGroupByHistogram — Used to perform a histogram computation (only for measure facets). Note: at most 100 buckets are allowed, the number of buckets is (max - min)/interval.
      - `interval` number, double, required — The bin size of the histogram buckets
      - `max` number, double, required — The maximum value for the measure used in the histogram (values greater than this one are filtered out)
      - `min` number, double, required — The minimum value for the measure used in the histogram (values smaller than this one are filtered out)
    - `limit` integer — The maximum buckets to return for this group by. Note: at most 10000 buckets are allowed. If grouping by multiple facets, the product of limits must not exceed 10000.
    - `missing` union — The value to use for logs that don't have the facet used to group by
      - string — The missing value to use if there is string valued facet.
      - number, double — The missing value to use if there is a number valued facet.
    - `sort` LogsAggregateSort — A sort rule
      - `aggregation` 'count' | 'cardinality' | 'pc75' | 'pc90' | 'pc95' | 'pc98' | 'pc99' | 'sum' | 'min' | 'max' | 'avg' | 'median' — An aggregation function
      - `metric` string — The metric to sort by (only used for `type=measure`)
      - `order` 'asc' | 'desc' — The order to use, ascending or descending
      - `type` 'alphabetical' | 'measure' — The type of sorting algorithm
    - `total` union — A resulting object to put the given computes in over all the matching records.
      - boolean — If set to true, creates an additional bucket labeled "$facet_total"
      - string — A string to use as the key value for the total bucket
      - number, double — A number to use as the key value for the total bucket
  - `options` LogsQueryOptions — Global query options that are used during the query. Note: These fields are currently deprecated and do not affect the query results.
    - `timeOffset` integer — The time offset (in seconds) to apply to the query.
    - `timezone` string — The timezone can be specified as GMT, UTC, an offset from UTC (like UTC+1), or as a Timezone Database identifier (like America/New_York).
  - `page` LogsAggregateRequestPage — Paging settings
    - `cursor` string — The returned paging point to use to get the next results. Note: at most 1000 results can be paged.

## Response `200`

OK

- LogsAggregateResponse — The response object for the logs aggregate API endpoint
  - `data` LogsAggregateResponseData — The query results
    - `buckets` LogsAggregateBucket[] — The list of matching buckets, one item per bucket
      - `by` object — The key, value pairs for each group by
      - `computes` object — A map of the metric name -> value for regular compute or list of values for a timeseries
  - `meta` LogsResponseMetadata — The metadata associated with a request
    - `elapsed` integer — The time elapsed in milliseconds
    - `page` LogsResponseMetadataPage — Paging attributes.
      - `after` string — The cursor to use to get the next results, if any. To make the next request, use the same parameters with the addition of the `page[cursor]`.
    - `request_id` string — The identifier of the request
    - `status` 'done' | 'timeout' — The status of the response
    - `warnings` LogsWarning[] — A list of warnings (non fatal errors) encountered, partial results might be returned if warnings are present in the response.
      - `code` string — A unique code for this type of warning
      - `detail` string — A detailed explanation of this specific warning
      - `title` string — A short human-readable summary of the warning

## Other responses

- `400` — Bad Request
- `403` — Not Authorized
- `429` — Too many requests

---

[API](https://skmtc.net/datadog/apis/api-v2.md) · [All operations](https://skmtc.net/datadog/apis/api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/datadog/api-v2/revisions/da68bf029e4c/schema)