> ## 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 aggregated events (batch)

> Same as GET but accepts a JSON body. Use for large multi-company queries that exceed URL length limits.

**Global queries** (no company filter) require at least one date range spanning 14 days or less.

**API versioning:** Defaults to v1. Pass `api_version=v0` for deprecated legacy schema.



## OpenAPI

````yaml POST /api/v1/events/
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/events/:
    post:
      tags:
        - Events
      summary: Get aggregated events (batch)
      description: >-
        Same as GET but accepts a JSON body. Use for large multi-company queries
        that exceed URL length limits.


        **Global queries** (no company filter) require at least one date range
        spanning 14 days or less.


        **API versioning:** Defaults to v1. Pass `api_version=v0` for deprecated
        legacy schema.
      operationId: events_create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventsPostRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/EventsPostRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/EventsPostRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventsPostResponse'
              examples:
                CompanyEventsPost:
                  value:
                    events:
                      - event_id: st_81e849b3-c465-455f-a008-056eb4d98faa
                        event_type: secondary_transaction
                        event_subtype: tender_offer
                        event_name: Tender Offer (2025)
                        event_date: '2025-12-05'
                        event_status: announced
                        event_last_updated_at: '2025-12-08T16:05:34.726238+00:00'
                        company:
                          id: '325'
                          slug: spacex
                          domain: spacex.com
                        data:
                          id: 81e849b3-c465-455f-a008-056eb4d98faa
                          updated_at: '2025-12-08T16:05:34.726238+00:00'
                          name: Tender Offer (2025)
                          transaction_type: tender_offer
                          transaction_amount: null
                          currency: USD
                          valuation: '800000000000.00'
                          price_per_share: null
                          announced_date: '2025-12-05'
                          closing_date: null
                          created_at: '2025-12-08T16:05:34.710277+00:00'
                          status: announced
                      - event_id: fr_7b3d1fed-0d27-484f-89a4-c10bec5f6d73
                        event_type: funding_round
                        event_subtype: growth
                        event_name: Growth 2019
                        event_date: '2019-04-11'
                        event_status: closed
                        event_last_updated_at: '2025-10-24T00:25:11.439575+00:00'
                        company:
                          id: '325'
                          slug: spacex
                          domain: spacex.com
                        data:
                          id: 7b3d1fed-0d27-484f-89a4-c10bec5f6d73
                          updated_at: '2025-10-24T00:25:11.439575+00:00'
                          name: Growth 2019
                          round_type: growth
                          amount_raised: '510000000.00'
                          currency: USD
                          valuation: '30000000000.00'
                          announced_date: '2019-04-11'
                          equities:
                            - name: Series J
                              equity_type: preferred
                              round_type: series_j
                              issue_price: '186.0000000'
                              issued_at: '2019-01-31T05:00:00+00:00'
                              updated_at: '2025-09-28T10:00:39.021272+00:00'
                          status: closed
                          is_extension: false
                    pagination:
                      page_size: 30
                      current_page_items: 2
                      total_items: 23
                      after_cursor: Start
                      before_cursor: null
                      next_link: null
                      prev_link: null
                    meta:
                      query_type: single-company
                      companies_count: 1
                      companies:
                        - id: '325'
                          slug: spacex
                          domain: spacex.com
                MultiCompanyEventsPost:
                  value:
                    events:
                      - event_id: st_0c601c12-6213-4093-8e5b-90febbb1056e
                        event_type: secondary_transaction
                        event_subtype: institutional_secondary
                        event_name: Direct Sale (2025)
                        event_date: '2025-09-01'
                        event_status: closed
                        event_last_updated_at: '2026-01-13T18:03:42.923112+00:00'
                        company:
                          id: '407'
                          slug: revolut
                          domain: revolut.com
                        data:
                          id: 0c601c12-6213-4093-8e5b-90febbb1056e
                          updated_at: '2026-01-13T18:03:42.923112+00:00'
                          name: Direct Sale (2025)
                          transaction_type: institutional_secondary
                          transaction_amount: '1000000000.00'
                          currency: USD
                          valuation: '75000000000.00'
                          price_per_share: '1381.06'
                          announced_date: '2025-09-01'
                          closing_date: '2025-09-05'
                          created_at: '2025-10-24T01:19:34.954929+00:00'
                          status: closed
                    pagination:
                      page_size: 30
                      current_page_items: 1
                      total_items: 1
                      after_cursor: Start
                      before_cursor: null
                      next_link: null
                      prev_link: null
                    meta:
                      query_type: multi-company
                      companies_count: 1
                      companies:
                        - id: '407'
                          slug: revolut
                          domain: revolut.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:
                    events: []
                    pagination:
                      page: 1
                      page_size: 30
                      total_pages: 0
                      total_count: 0
                      has_next: false
                      has_previous: false
                    meta:
                      query_type: single-company
                      companies_count: 0
                      companies: []
                  description: Empty result with offset-based pagination (default mode).
          description: Paginated list of events with metadata. 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: 'Company not found for id(s): [''999'']'
          description: One or more requested company IDs or domains were not found.
        '500':
          content:
            text/plain:
              schema:
                type: string
                example: Internal server error
          description: Internal server error.
      security:
        - SacraAPIAuthentication: []
components:
  schemas:
    EventsPostRequest:
      type: object
      properties:
        start_date:
          type: string
          format: date
          description: Filter events on or after this date (ISO 8601).
        end_date:
          type: string
          format: date
          description: Filter events on or before this date (ISO 8601).
        created_at_gte:
          type: string
          format: date-time
          description: Filter events created at or after this datetime.
        created_at_lte:
          type: string
          format: date-time
          description: Filter events created at or before this datetime.
        updated_at_gte:
          type: string
          format: date-time
          description: Filter events updated at or after this datetime.
        updated_at_lte:
          type: string
          format: date-time
          description: Filter events updated at or before this datetime.
        company_domain:
          type: string
          description: Filter by a single company domain (e.g. `spacex.com`).
        company_uid:
          type: string
          description: Filter by a single company slug/prismic UID.
        company_id:
          type: string
          description: Filter by a single company ID.
        company_domains:
          type: array
          items:
            type: string
          description: List of company domains.
        company_ids:
          type: array
          items:
            type: string
          description: List of company IDs.
        types:
          type: string
          description: >-
            Comma-separated event types: `funding-round`,
            `secondary-transaction`, `company-milestone`, `corporate-action`.
        subtypes:
          type: string
          description: Comma-separated event subtypes (e.g. `stock_split`, `ipo`).
        include_citations:
          type: boolean
          default: false
          description: Attach citation payloads to events.
        pagination:
          allOf:
            - $ref: '#/components/schemas/PaginationEnum'
          description: |-
            Pagination mode. Default: `page`.

            * `page` - page
            * `cursor` - cursor
        page:
          type: integer
          description: 'Page number (offset pagination). Default: 1.'
        page_size:
          type: integer
          description: 'Results per page. Default: 30, max: 100.'
        page_after:
          type: string
          description: Cursor for the next page (cursor pagination only).
        page_before:
          type: string
          description: Cursor for the previous page (cursor pagination only).
        api_version:
          allOf:
            - $ref: '#/components/schemas/ApiVersionEnum'
          description: |-
            Response schema version. Default: `v1`.

            * `v1` - v1
            * `v0` - v0
            * `legacy` - legacy
    EventsPostResponse:
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/EventPost'
        pagination:
          $ref: '#/components/schemas/EventsPostPagination'
        meta:
          $ref: '#/components/schemas/EventsPostMeta'
      required:
        - events
        - meta
        - pagination
    PaginationEnum:
      enum:
        - page
        - cursor
      type: string
      description: |-
        * `page` - page
        * `cursor` - cursor
    ApiVersionEnum:
      enum:
        - v1
        - v0
        - legacy
      type: string
      description: |-
        * `v1` - v1
        * `v0` - v0
        * `legacy` - legacy
    EventPost:
      type: object
      properties:
        event_id:
          type: string
        event_type:
          type: string
        event_subtype:
          type: string
          nullable: true
        event_name:
          type: string
        event_date:
          type: string
        event_status:
          type: string
        event_last_updated_at:
          type: string
          format: date-time
        company:
          $ref: '#/components/schemas/EventPostCompanyRef'
        data:
          type: object
          additionalProperties: {}
          description: Event-specific payload. Shape varies by `event_type`.
        citations:
          $ref: '#/components/schemas/EventPostCitations'
      required:
        - company
        - data
        - event_date
        - event_id
        - event_last_updated_at
        - event_name
        - event_status
        - event_subtype
        - event_type
    EventsPostPagination:
      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
    EventsPostMeta:
      type: object
      properties:
        query_type:
          type: string
        companies_count:
          type: integer
        companies:
          type: array
          items:
            $ref: '#/components/schemas/EventsPostMetaCompany'
      required:
        - companies
        - companies_count
        - query_type
    EventPostCompanyRef:
      type: object
      properties:
        id:
          type: string
        slug:
          type: string
        domain:
          type: string
      required:
        - domain
        - id
        - slug
    EventPostCitations:
      type: object
      properties:
        summary:
          $ref: '#/components/schemas/EventPostCitationsSummary'
        items:
          type: array
          items:
            $ref: '#/components/schemas/EventPostCitationItem'
      required:
        - items
        - summary
    EventsPostMetaCompany:
      type: object
      properties:
        id:
          type: string
        slug:
          type: string
        domain:
          type: string
      required:
        - domain
        - id
        - slug
    EventPostCitationsSummary:
      type: object
      properties:
        count:
          type: integer
        latest_updated_at:
          type: string
          format: date-time
          nullable: true
      required:
        - count
        - latest_updated_at
    EventPostCitationItem:
      type: object
      properties:
        signal_id:
          type: string
          nullable: true
          description: Identifier for the underlying fact/signal linked to these sources.
        signal_title:
          type: string
          nullable: true
        captured_at:
          type: string
          format: date-time
          nullable: true
        sources:
          type: array
          items:
            $ref: '#/components/schemas/EventPostCitationSource'
      required:
        - captured_at
        - signal_id
        - signal_title
        - sources
    EventPostCitationSource:
      type: object
      properties:
        link:
          type: string
          format: uri
        headline:
          type: string
          nullable: true
        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>`

````