> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sacra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get metric observations (batch)

> Same as GET but accepts a JSON body. Use for large multi-company queries.

**Company filters:** Provide single-company filters (`company_id`, `company_domain`) or multi-company filters (`company_ids`, `company_domains`), but not both.

**Global queries** (no company filter) require at least one date range (`measurement_end_date`, `comparison_window_end_date`, `created_at`, or `updated_at`) spanning 14 days or less.



## OpenAPI

````yaml POST /api/v1/metrics/
openapi: 3.0.3
info:
  title: Sacra API
  version: 1.0.0
  description: >-
    The Sacra API currently supports querying News, Documents, Companies and
    Categories that enable you to use Sacra research within your own
    application.


    ## **Getting started guide**


    To start using the APIs, you need to:


    - Only available to **Platforms** and **Funds** tier members. (See
    [here](https://sacra.com/pricing/))
        
    - You must use a valid API Key to send requests to the API endpoints. You
    can generate your API key in the Api Keys section of your [Organization
    Settings](https://sacra.com/orgs/settings/general/).
        
    - The API returns request responses in JSON format. When an API request
    returns an error, it is sent in the JSON response as an error key.
        

    ## Authentication


    The Sacra API uses Tokens for authentication.


    You can generate a Sacra API Key/Token in the Api Keys section of your
    [Organization Settings](https://sacra.com/orgs/settings/general/).


    You must include an API Key/Token in each request to the Sacra API with the
    **Authorization** request header.


    ### Authentication error response


    If a Token is missing, malformed, or invalid, you will receive an HTTP 401
    Unauthorized response code.


    ### **Need some help?**


    In case you have questions, we will eventually provide tutorials and a FAQ
    page. But for now you can check out the
    [#developers](https://discord.gg/mTswyV8gg3) channel in our community
    [Discord](https://discord.gg/mTswyV8gg3), there’s a good chance our
    community has an answer for you.


    ## Authorization


    | **Key** | **Value** |

    | --- | --- |

    | Authorization | Token {{API_KEY}} |
servers:
  - url: https://sacra.com
    description: Production
security: []
tags:
  - name: Companies
  - name: Categories
  - name: Events
  - name: News
  - name: Documents
  - name: Filings
  - name: Embeds
  - name: Metrics
  - name: Funding (Legacy)
paths:
  /api/v1/metrics/:
    post:
      tags:
        - Metrics
      summary: Get metric observations (batch)
      description: >-
        Same as GET but accepts a JSON body. Use for large multi-company
        queries.


        **Company filters:** Provide single-company filters (`company_id`,
        `company_domain`) or multi-company filters (`company_ids`,
        `company_domains`), but not both.


        **Global queries** (no company filter) require at least one date range
        (`measurement_end_date`, `comparison_window_end_date`, `created_at`, or
        `updated_at`) spanning 14 days or less.
      operationId: metrics_create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetricsPostRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/MetricsPostRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/MetricsPostRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricsPostResponse'
              examples:
                CompanyRevenueMetricsPost:
                  value:
                    metrics:
                      - metric_id: 604e0090-a7ac-470c-ae63-376e0f5055f1
                        metric_definition:
                          base: trailing_revenue
                          view: value
                          base_period: year
                          base_forward: null
                          growth_period: null
                          growth_period_length: null
                        measurement:
                          scenario: historical
                          end_date: '2025-12-31'
                          custom_start_date: null
                          comparison_window_end_date: null
                          comparison_window_custom_start_date: null
                          type: equals
                          unit_kind: currency
                          currency_code: USD
                          amount: 2200000000
                          low: null
                          high: null
                          scope_name: null
                          scope_type: null
                          status: Active
                        updated_at: '2026-02-26T20:27:13.693661+00:00'
                        created_at: '2026-02-25T20:17:24.752169+00:00'
                        company:
                          id: '239'
                          slug: kraken
                          domain: kraken.com
                        citations:
                          summary:
                            count: 1
                            latest_updated_at: '2026-02-25T20:17:40.923084+00:00'
                          sources:
                            - link: >-
                                https://blog.kraken.com/news/kraken-2025-financials
                              headline: Kraken 2025 Financials
                              quote: >-
                                Adjusted revenue reached $2.2 billion,
                                representing 33% year-over-year growth.
                              publication: blog.kraken.com
                              type: article
                    pagination:
                      page_size: 30
                      current_page_items: 1
                      total_items: 13
                      after_cursor: Start
                      before_cursor: null
                      next_link: null
                      prev_link: null
                    meta:
                      query_type: single-company
                      companies_count: 1
                      companies:
                        - id: '239'
                          slug: kraken
                          domain: kraken.com
                MultiCompanyMetricsPost:
                  value:
                    metrics:
                      - metric_id: e8429dad-2c5f-4e92-aff3-538ca28d59b6
                        metric_definition:
                          base: trailing_revenue
                          view: value
                          base_period: year
                          base_forward: null
                          growth_period: null
                          growth_period_length: null
                        measurement:
                          scenario: projection
                          end_date: '2030-12-31'
                          custom_start_date: null
                          comparison_window_end_date: null
                          comparison_window_custom_start_date: null
                          type: equals
                          unit_kind: currency
                          currency_code: USD
                          amount: 213000000000
                          low: null
                          high: null
                          scope_name: null
                          scope_type: null
                          status: Active
                        updated_at: '2026-02-26T20:27:13.843770+00:00'
                        created_at: '2026-02-25T20:17:24.704612+00:00'
                        company:
                          id: '579'
                          slug: openai
                          domain: openai.com
                        citations:
                          summary:
                            count: 1
                            latest_updated_at: '2026-02-25T20:17:40.830815+00:00'
                          sources: []
                      - metric_id: ab346558-9373-4d66-ab1b-bb3a1f9b6450
                        metric_definition:
                          base: trailing_revenue
                          view: value
                          base_period: year
                          base_forward: null
                          growth_period: null
                          growth_period_length: null
                        measurement:
                          scenario: projection
                          end_date: '2028-12-31'
                          custom_start_date: null
                          comparison_window_end_date: null
                          comparison_window_custom_start_date: null
                          type: equals
                          unit_kind: currency
                          currency_code: USD
                          amount: 70000000000
                          low: null
                          high: null
                          scope_name: null
                          scope_type: null
                          status: Active
                        updated_at: '2026-02-26T20:27:13.082265+00:00'
                        created_at: '2026-02-25T20:17:24.771316+00:00'
                        company:
                          id: '649'
                          slug: anthropic
                          domain: anthropic.com
                        citations:
                          summary:
                            count: 2
                            latest_updated_at: '2026-02-25T20:17:40.971313+00:00'
                          sources: []
                    pagination:
                      page_size: 30
                      current_page_items: 2
                      total_items: 43
                      after_cursor: Start
                      before_cursor: null
                      next_link: null
                      prev_link: null
                    meta:
                      query_type: multi-company
                      companies_count: 2
                      companies:
                        - id: '579'
                          slug: openai
                          domain: openai.com
                        - id: '649'
                          slug: anthropic
                          domain: anthropic.com
                  description: >-
                    Multi-company query via POST body with company_domains list.
                    Note next_link is null for POST (use page_after cursor
                    directly).
                EmptyResultsPost:
                  value:
                    metrics: []
                    pagination:
                      page_size: 30
                      current_page_items: 0
                      total_items: 0
                      after_cursor: Start
                      before_cursor: null
                      next_link: null
                      prev_link: null
                    meta:
                      query_type: global
                      companies_count: 0
                      companies: []
                  description: No metrics match the given filters.
          description: >-
            Paginated list of metric observations with citations. Same shape as
            GET.
        '400':
          content:
            text/plain:
              schema:
                type: string
                example: >-
                  Provide either single-company or multi-company filters, not
                  both.
          description: Invalid parameters.
        '404':
          content:
            text/plain:
              schema:
                type: string
                example: 'Bad request: Company not found for domain: example.com'
          description: Company not found.
        '500':
          content:
            text/plain:
              schema:
                type: string
                example: Internal server error
          description: Internal server error.
      security:
        - SacraAPIAuthentication: []
components:
  schemas:
    MetricsPostRequest:
      type: object
      properties:
        company_id:
          type: string
          description: Filter by a single company ID.
        company_domain:
          type: string
          description: Filter by a single company domain (e.g. `stripe.com`).
        company_ids:
          type: array
          items:
            type: string
          description: List of company IDs.
        company_domains:
          type: array
          items:
            type: string
          description: List of company domains.
        metric_base:
          type: string
          description: >-
            Comma-separated `metric_definition.base` values (e.g.
            `revenue,arr`).
        metric_view:
          type: string
          description: >-
            Comma-separated `metric_definition.view` values (e.g.
            `value,growth`).
        measurement_scenario:
          type: string
          description: >-
            Comma-separated `measurement.scenario` values (e.g.
            `historical,projection`).
        base_period:
          type: string
          description: Comma-separated `metric_definition.base_period` values.
        growth_period:
          type: string
          description: Comma-separated `metric_definition.growth_period` values.
        measurement_end_date_gte:
          type: string
          format: date-time
          description: Filter where `measurement.end_date` >= this value (ISO 8601).
        measurement_end_date_lte:
          type: string
          format: date-time
          description: Filter where `measurement.end_date` <= this value (ISO 8601).
        comparison_window_end_date_gte:
          type: string
          format: date-time
          description: >-
            Filter where `measurement.comparison_window_end_date` >= this value
            (ISO 8601).
        comparison_window_end_date_lte:
          type: string
          format: date-time
          description: >-
            Filter where `measurement.comparison_window_end_date` <= this value
            (ISO 8601).
        created_at_gte:
          type: string
          format: date-time
          description: Filter metrics created on or after this datetime (ISO 8601).
        created_at_lte:
          type: string
          format: date-time
          description: Filter metrics created on or before this datetime (ISO 8601).
        updated_at_gte:
          type: string
          format: date-time
          description: Filter metrics updated on or after this datetime (ISO 8601).
        updated_at_lte:
          type: string
          format: date-time
          description: Filter metrics updated on or before this datetime (ISO 8601).
        include_all_signal_evidence:
          type: boolean
          default: false
          description: 'When true, include all SignalEvidence rows. Default: false.'
        page_size:
          type: integer
          description: 'Results per page. Default: 30, max: 100.'
        page_after:
          type: string
          description: Cursor for the next page.
        page_before:
          type: string
          description: Cursor for the previous page.
    MetricsPostResponse:
      type: object
      properties:
        metrics:
          type: array
          items:
            $ref: '#/components/schemas/MetricPostObservation'
        pagination:
          $ref: '#/components/schemas/MetricsPostPagination'
        meta:
          $ref: '#/components/schemas/MetricsPostMeta'
      required:
        - meta
        - metrics
        - pagination
    MetricPostObservation:
      type: object
      properties:
        metric_id:
          type: string
          format: uuid
        metric_definition:
          $ref: '#/components/schemas/MetricPostDefinition'
        measurement:
          $ref: '#/components/schemas/MetricPostMeasurement'
        updated_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        company:
          $ref: '#/components/schemas/MetricPostCompanyRef'
        citations:
          $ref: '#/components/schemas/MetricPostCitations'
      required:
        - citations
        - company
        - created_at
        - measurement
        - metric_definition
        - metric_id
        - updated_at
    MetricsPostPagination:
      type: object
      properties:
        page_size:
          type: integer
        current_page_items:
          type: integer
        total_items:
          type: integer
        after_cursor:
          type: string
          nullable: true
        before_cursor:
          type: string
          nullable: true
        next_link:
          type: string
          nullable: true
        prev_link:
          type: string
          nullable: true
      required:
        - after_cursor
        - before_cursor
        - current_page_items
        - next_link
        - page_size
        - prev_link
        - total_items
    MetricsPostMeta:
      type: object
      properties:
        query_type:
          type: string
        companies_count:
          type: integer
        companies:
          type: array
          items:
            $ref: '#/components/schemas/MetricsPostMetaCompany'
      required:
        - companies
        - companies_count
        - query_type
    MetricPostDefinition:
      type: object
      properties:
        base:
          type: string
        view:
          type: string
        base_period:
          type: string
          nullable: true
        base_forward:
          type: string
          nullable: true
        growth_period:
          type: string
          nullable: true
        growth_period_length:
          type: integer
          nullable: true
      required:
        - base
        - base_forward
        - base_period
        - growth_period
        - growth_period_length
        - view
    MetricPostMeasurement:
      type: object
      properties:
        scenario:
          type: string
        end_date:
          type: string
        custom_start_date:
          type: string
          nullable: true
        comparison_window_end_date:
          type: string
          nullable: true
        comparison_window_custom_start_date:
          type: string
          nullable: true
        type:
          type: string
        unit_kind:
          type: string
        currency_code:
          type: string
          nullable: true
        amount:
          type: number
          format: double
          nullable: true
        low:
          type: number
          format: double
          nullable: true
        high:
          type: number
          format: double
          nullable: true
        scope_name:
          type: string
          nullable: true
        scope_type:
          type: string
          nullable: true
        status:
          type: string
      required:
        - amount
        - comparison_window_custom_start_date
        - comparison_window_end_date
        - currency_code
        - custom_start_date
        - end_date
        - high
        - low
        - scenario
        - scope_name
        - scope_type
        - status
        - type
        - unit_kind
    MetricPostCompanyRef:
      type: object
      properties:
        id:
          type: string
        slug:
          type: string
        domain:
          type: string
      required:
        - domain
        - id
        - slug
    MetricPostCitations:
      type: object
      properties:
        summary:
          $ref: '#/components/schemas/MetricPostCitationsSummary'
        sources:
          type: array
          items:
            $ref: '#/components/schemas/MetricPostCitationSource'
      required:
        - sources
        - summary
    MetricsPostMetaCompany:
      type: object
      properties:
        id:
          type: string
        slug:
          type: string
        domain:
          type: string
      required:
        - domain
        - id
        - slug
    MetricPostCitationsSummary:
      type: object
      properties:
        count:
          type: integer
        latest_updated_at:
          type: string
          format: date-time
          nullable: true
      required:
        - count
        - latest_updated_at
    MetricPostCitationSource:
      type: object
      properties:
        link:
          type: string
        headline:
          type: string
        quote:
          type: string
          nullable: true
        publication:
          type: string
          nullable: true
        type:
          type: string
      required:
        - headline
        - link
        - publication
        - quote
        - type
  securitySchemes:
    SacraAPIAuthentication:
      type: apiKey
      in: header
      name: Authorization
      description: |-
        Authenticate using one of two formats:

        - **Organization/user token:** `Token <your-token>`
        - **Stytch JWT:** `Bearer <your-jwt>`

````