---
title: "Metrics API for aggregated analytics"
method: POST
path: "/metrics"
tags: ["Content Metrics"]
---

# Metrics API for aggregated analytics

`POST /metrics`

## Metrics

The Metrics API provides at-a-glance analytics over all our news & regulatory content. It allows users to monitor, visualise and understand news coverage over time, and enables direct integration with Business Intelligence & data visualisation tools

The `/metrics` endpoint supports the same expressive query language as our `/search` endpoint, but rather than returning metadata for each individual piece of content, provides aggregated metrics over the results which can be sliced and diced along multiple dimensions: date, publication source, publication country, topics, entities, sentiment, etc.. The limits for these parameters are the same as on the `/search` endpoint (i.e. at most 200 entities, 100 topics...). The exact numbers for each field are detailed in the schema below.

Example questions the Metrics API can answer in 1 API request / response:

- How is the coverage (number of articles) and sentiment (negative, neutral and positive coverage) towards my suppliers changing…
  - …over time?
  - …and / or in relation to a set of key ESG topics?
  - …and / or by country of publication?
- How does overall sentiment towards companies in my portfolio vary by country?
- What are the top publications (by volume) covering the topics of Cleantech and Sustainable Investments?

> ⚠️  **Metrics requests are limited to a maximum number of 10,000 aggregation groups**
>
> If the number of groups resulting from a query exceeds that limit, the API will return an HTTP 400 response (Bad Request).
> We would recommend in such instance to break down the metrics query into multiple queries and combine the results. For instance, in order to get daily coverage metrics for 100 entities over 12 months (100 entities X 365 days = 36,500 aggregation groups), you could achieve this with either:
>
> - 4 requests for groups of 25 entities (25 entities X 365 days = 9,125 groups per request)
> - 12 monthly requests for 100 entities (100 entities X 31 days = 3,100 groups per request)

> ℹ️  **For better performance, use the `where` field to select only relevant documents**
>
> Before computing the aggregated metrics, the `where` field is used to reduce the number of
> documents the system has to process. The more precise the subset of documents is, the faster the
> results will be computed.

> ℹ️  **Weekly Aggregation**
>
> The date associated with each aggregation bucket in the results will be the date of the first day of that week, so if you query from 2021-01-01 (which was a Friday), the date associated with the first bucket would be 2020-12-28 which was the Monday of the same week.

## Request body

- MetricsQuery
  - `where` DocumentMatch, required
    - `story-id` union
      - object
        - `eq` string, uuid, required
        - `any` unknown
      - object
        - `any` ResourceId[], required
    - `entities` DocumentEntitiesMatch
      - `id` union, required
        - object
          - `eq` string, uuid, required
          - `any` unknown[]
            - unknown
          - `all` unknown[]
            - unknown
        - object
          - `any` ResourceId[], required
          - `all` unknown[]
            - unknown
        - object
          - `all` ResourceId[], required
          - `any` unknown[]
            - unknown
      - `salient-only` boolean — Only return documents for which these entities are salient
      - `mentions` MentionPositionMatch — Note that mentions found in `summary` or `quotation` are a subset of the mentions found in the `full content`.
        - `position` 'title' | 'title or summary' | 'full content' | 'quotes only', required
    - `published-at` DateTimeRangeMatch
      - `gt` union
        - string, date — A date based on the IETF RFC 3339 format (e.g. `2023-01-01`). Note that a day is the span of time between 00:00:00 and 23:59:59 based on the UTC timezone. You may prefer using the `date-time` option to match days in a different timezone.
        - string, date-time — A date and time based on the IETF RFC 3339 format (e.g. `2023-01-01T13:37:00` or `2023-01-01T13:37:00Z` for UTC, `2023-01-01T09:37:00-05:00` for EST). Note that UTC is used by default.
      - `gte` union
        - string, date — A date based on the IETF RFC 3339 format (e.g. `2023-01-01`). Note that a day is the span of time between 00:00:00 and 23:59:59 based on the UTC timezone. You may prefer using the `date-time` option to match days in a different timezone.
        - string, date-time — A date and time based on the IETF RFC 3339 format (e.g. `2023-01-01T13:37:00` or `2023-01-01T13:37:00Z` for UTC, `2023-01-01T09:37:00-05:00` for EST). Note that UTC is used by default.
      - `lt` union
        - string, date — A date based on the IETF RFC 3339 format (e.g. `2023-01-01`). Note that a day is the span of time between 00:00:00 and 23:59:59 based on the UTC timezone. You may prefer using the `date-time` option to match days in a different timezone.
        - string, date-time — A date and time based on the IETF RFC 3339 format (e.g. `2023-01-01T13:37:00` or `2023-01-01T13:37:00Z` for UTC, `2023-01-01T09:37:00-05:00` for EST). Note that UTC is used by default.
      - `lte` union
        - string, date — A date based on the IETF RFC 3339 format (e.g. `2023-01-01`). Note that a day is the span of time between 00:00:00 and 23:59:59 based on the UTC timezone. You may prefer using the `date-time` option to match days in a different timezone.
        - string, date-time — A date and time based on the IETF RFC 3339 format (e.g. `2023-01-01T13:37:00` or `2023-01-01T13:37:00Z` for UTC, `2023-01-01T09:37:00-05:00` for EST). Note that UTC is used by default.
    - `source` SourceMatch
      - `id` union
        - object
          - `eq` string, uuid, required
          - `any` unknown
        - object
          - `any` ResourceId[], required
      - `country` union
        - EqualsTerm
          - `eq` string, required
        - AnyTerms
          - `any` string[], required
      - `region` union
        - EqualsTerm
          - `eq` string, required
        - AnyTerms
          - `any` string[], required
      - `subregion` union
        - EqualsTerm
          - `eq` string, required
        - AnyTerms
          - `any` string[], required
    - `keywords` DocumentKeywordsMatch — Note that to use inclusion keywords, you will also need to include one of `entities`, `sources` or `topics` in your `where` clause.
      - `value` union, required
        - object — There is a 50 word limit for keywords across inclusion and exclusion. See the section **Keyword limitations** above for more details.
          - `eq` string, required
        - object — There is a 50 word limit for keywords across inclusion and exclusion. See the section **Keyword limitations** above for more details.
          - `any` string[], required
        - object — There is a 50 word limit for keywords across inclusion and exclusion. See the section **Keyword limitations** above for more details.
          - `all` string[], required
      - `mentions` MentionPositionMatch — Note that mentions found in `summary` or `quotation` are a subset of the mentions found in the `full content`.
        - `position` 'title' | 'title or summary' | 'full content' | 'quotes only', required
    - `topics` DocumentTopicsMatch
      - `id` union, required
        - object
          - `eq` string, uuid, required
          - `any` unknown
          - `all` unknown
        - object
          - `any` ResourceId[], required
          - `all` unknown
        - object
          - `all` ResourceId[], required
          - `any` unknown
    - `categories` CategoriesMatch
      - `id` union, required
        - object
          - `eq` string, uuid, required
          - `any` unknown
          - `all` unknown
        - object
          - `any` ResourceId[], required
          - `all` unknown
        - object
          - `all` ResourceId[], required
          - `any` unknown
    - `language` union
      - object
        - `eq` string, required — Language (e.g. `English`, `Chinese`, `Spanish`, `German`, `Japanese`...)
      - object
        - `any` string[], required — A list of languages (e.g. `English`, `Chinese`, `Spanish`, `German`, `Japanese`...)
    - `media-type` union
      - EqualsMediaType
        - `eq` 'online' | 'print', required
      - AnyMediaType
        - `any` MediaType[], required
  - `exclude` ExcludeClause
    - `entities` EntitiesExclusion
      - `id` object, required
        - `any` ResourceId[], required
    - `topics` TopicsExclusion
      - `id` object, required
        - `any` ResourceId[], required
    - `source` union
      - SourceExclusion
        - `id` object, required
          - `any` ResourceId[], required
      - CountryExclusion
        - `country` AnyTerms, required
          - `any` string[], required
    - `keywords` KeywordsExclusion
      - `value` AnyTerms, required
        - `any` string[], required
  - `aggregations` AggregationsQuery, required
    - `group-by` AggregationDimensionKey[], required
    - `options` AggregationQueryOptions
      - `published-at` AggregationQueryDateIntervalOptions
        - `interval` 'month' | 'week' | 'day', required
      - `topic` AggregationQueryResourcesIncludeOption
        - `include` ResourceId[], required
      - `iptc-media-topic` AggregationQueryResourcesIncludeOption
        - `include` ResourceId[], required
      - `entity` AggregationQueryResourcesIncludeOption
        - `include` ResourceId[], required
      - `source.country` AggregationQueryTermsIncludeOptions
        - `include` string[]
        - `size` integer
      - `language` AggregationQueryTermsIncludeOptions
        - `include` string[]
        - `size` integer
      - `source` AggregationQuerySourceOptions
        - `size` integer
        - `include` ResourceId[]
    - `metrics` AggregationMetricKey[], required — Metrics to compute for each group-by dimension

## Response `200`

Returns aggregate metrics for documents matching the search query

- MetricsResponse
  - `aggregations` Aggregation[], required

---

[API](https://skmtc.net/signal-ai/apis/signal-ai-api.md) · [All operations](https://skmtc.net/signal-ai/apis/signal-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/signal-ai/signal-ai-api/versions/867c43388206/schema)