Svix Statistics API

openapi: 3.2.0
info:
  title: Svix Statistics API
  description: Welcome to the Svix API documentation!
  version: 1.922.0
  x-logo:
    url: https://www.svix.com/static/img/brand-padded.svg
    altText: Svix Logo
servers:
- url: https://api.eu.svix.com
  description: The Svix EU region
- url: https://api.us.svix.com
  description: The Svix US region
- url: https://api.ca.svix.com
  description: The Svix Canada region
- url: https://api.au.svix.com
  description: The Svix Australia region
- url: https://api.in.svix.com
  description: The Svix India region
tags:
- name: Statistics
  description: Generate statistics about your Svix utilization
paths:
  /api/v1/stats/usage/event-types:
    put:
      tags:
      - Statistics
      summary: Aggregate Event Types
      description: 'Creates a background task to calculate the listed event types for all apps in the organization.


        Note that this endpoint is asynchronous. You will need to poll the `Get Background Task` endpoint to

        retrieve the results of the operation.


        The completed background task will return a payload like the following:

        ```json

        {

        "id": "qtask_33qe39Stble9Rn3ZxFrqL5ZSsjT",

        "status": "finished",

        "task": "event-type.aggregate",

        "data": {

        "event_types": [

        {

        "appId": "app_33W1An2Zz5cO9SWbhHsYyDmVC6m",

        "explicitlySubscribedEventTypes": ["user.signup", "user.deleted"],

        "hasCatchAllEndpoint": false

        }

        ]

        }

        }

        ```'
      operationId: v1.statistics.aggregate-event-types
      responses:
        '202':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AggregateEventTypesOut'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
      security:
      - HTTPBearer: []
      x-codeSamples:
      - lang: TypeScript
        label: JavaScript
        source: const response = await svix.statistics.aggregateEventTypes();
      - lang: TypeScript
        label: TypeScript
        source: const response = await svix.statistics.aggregateEventTypes();
      - lang: Python
        label: Python
        source: response = svix.statistics.aggregate_event_types()
      - lang: Python
        label: Python (Async)
        source: response = await svix.statistics.aggregate_event_types()
      - lang: Go
        label: Go
        source: response, err := svix.Statistics.AggregateEventTypes(ctx)
      - lang: Kotlin
        label: Kotlin
        source: val response = svix.statistics.aggregateEventTypes()
      - lang: Java
        label: Java
        source: var response = svix.getStatistics().aggregateEventTypes();
      - lang: Ruby
        label: Ruby
        source: response = svix.statistics.aggregate_event_types
      - lang: Rust
        label: Rust
        source: let response = svix.statistics().aggregate_event_types().await?;
      - lang: C#
        label: C#
        source: var response = svix.Statistics.AggregateEventTypes();
      - lang: PHP
        label: PHP
        source: $response = $svix->statistics->aggregateEventTypes();
      - lang: Shell
        label: CLI
        source: svix statistics aggregate-event-types
      - lang: Shell
        label: cURL
        source: "curl -X 'PUT' \\\n  'https://api.eu.svix.com/api/v1/stats/usage/event-types' \\\n  -H 'Authorization: Bearer AUTH_TOKEN' \\\n  -H 'Accept: application/json'"
  /api/v1/stats/usage/app:
    post:
      tags:
      - Statistics
      summary: Aggregate App Stats
      description: 'Creates a background task to calculate the number of message attempts (`messageDestinations`) made for all applications in the environment.


        Note that this endpoint is asynchronous. You will need to poll the `Get Background Task` endpoint to

        retrieve the results of the operation.


        The completed background task will return a payload like the following:

        ```json

        {

        "id": "qtask_33qe39Stble9Rn3ZxFrqL5ZSsjT",

        "status": "finished",

        "task": "application.stats",

        "data": {

        "appStats": [

        {

        "messageDestinations": 2,

        "appId": "app_33W1An2Zz5cO9SWbhHsYyDmVC6m",

        "appUid": null

        }

        ]

        }

        }

        ```'
      operationId: v1.statistics.aggregate-app-stats
      parameters:
      - in: header
        name: idempotency-key
        description: The request's idempotency key
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppUsageStatsIn'
        required: true
      responses:
        '202':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppUsageStatsOut'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
      security:
      - HTTPBearer: []
      x-codeSamples:
      - lang: TypeScript
        label: JavaScript
        source: "const response = await svix.statistics.aggregateAppStats({\n  since: new Date(\"2025-10-02T20:28:42+00:00\"),\n  until: new Date(\"2025-10-02T20:28:42+00:00\"),\n  appIds: [],\n});"
      - lang: TypeScript
        label: TypeScript
        source: "const response = await svix.statistics.aggregateAppStats({\n  since: new Date(\"2025-10-02T20:28:42+00:00\"),\n  until: new Date(\"2025-10-02T20:28:42+00:00\"),\n  appIds: [],\n});"
      - lang: Python
        label: Python
        source: "response = svix.statistics.aggregate_app_stats(\n    AppUsageStatsIn(\n        since=datetime.fromisoformat(\"2025-10-02T20:28:42+00:00\"),\n        until=datetime.fromisoformat(\"2025-10-02T20:28:42+00:00\"),\n        app_ids=[],\n    ),\n)"
      - lang: Python
        label: Python (Async)
        source: "response = await svix.statistics.aggregate_app_stats(\n    AppUsageStatsIn(\n        since=datetime.fromisoformat(\"2025-10-02T20:28:42+00:00\"),\n        until=datetime.fromisoformat(\"2025-10-02T20:28:42+00:00\"),\n        app_ids=[],\n    ),\n)"
      - lang: Go
        label: Go
        source: "response, err := svix.Statistics.AggregateAppStats(\n\tctx,\n\tAppUsageStatsIn{\n\t\tSince:  time.Date(2025, 10, 2, 20, 28, 42, 0, time.UTC),\n\t\tUntil:  time.Date(2025, 10, 2, 20, 28, 42, 0, time.UTC),\n\t\tAppIds: []string{},\n\t},\n\tnil,\n)"
      - lang: Kotlin
        label: Kotlin
        source: "val response =\n    svix.statistics.aggregateAppStats(\n        AppUsageStatsIn(\n            since = Instant.parse(\"2025-10-02T20:28:42+00:00\"),\n            until = Instant.parse(\"2025-10-02T20:28:42+00:00\"),\n            appIds = setOf(),\n        )\n    )"
      - lang: Java
        label: Java
        source: "var response = svix.getStatistics()\n        .aggregateAppStats(new AppUsageStatsIn()\n            .since(OffsetDateTime.parse(\"2025-10-02T20:28:42+00:00\"))\n            .until(OffsetDateTime.parse(\"2025-10-02T20:28:42+00:00\"))\n            .appIds(Set.of()));"
      - lang: Ruby
        label: Ruby
        source: "response = svix\n  .statistics\n  .aggregate_app_stats({since: \"2025-10-02T20:28:42+00:00\", until: \"2025-10-02T20:28:42+00:00\", appIds: []})"
      - lang: Rust
        label: Rust
        source: "let response = svix\n    .statistics()\n    .aggregate_app_stats(\n        AppUsageStatsIn {\n            since: \"2025-10-02T20:28:42+00:00\".to_string(),\n            until: \"2025-10-02T20:28:42+00:00\".to_string(),\n            app_ids: Some(vec![]),\n        },\n        None,\n    )\n    .await?;"
      - lang: C#
        label: C#
        source: "var response = svix.Statistics.AggregateAppStats(\n    new AppUsageStatsIn\n    {\n        Since = DateTime.Parse(\"2025-10-02T20:28:42+00:00\"),\n        Until = DateTime.Parse(\"2025-10-02T20:28:42+00:00\"),\n        AppIds = [],\n    }\n);"
      - lang: PHP
        label: PHP
        source: "$response = $svix->statistics->aggregateAppStats(\n    AppUsageStatsIn::create(\n        since: new DateTimeImmutable(\"2025-10-02T20:28:42+00:00\"),\n        until: new DateTimeImmutable(\"2025-10-02T20:28:42+00:00\")\n    )\n    ->withAppIds([])\n);"
      - lang: Shell
        label: CLI
        source: "svix statistics aggregate-app-stats '{\n    \"since\": \"2025-10-02T20:28:42+00:00\",\n    \"until\": \"2025-10-02T20:28:42+00:00\",\n    \"appIds\": []\n  }'"
      - lang: Shell
        label: cURL
        source: "curl -X 'POST' \\\n  'https://api.eu.svix.com/api/v1/stats/usage/app' \\\n  -H 'Authorization: Bearer AUTH_TOKEN' \\\n  -H 'Accept: application/json' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"since\": \"2025-10-02T20:28:42+00:00\",\n    \"until\": \"2025-10-02T20:28:42+00:00\",\n    \"appIds\": []\n  }'"
  /api/v1/stats/endpoint/count:
    get:
      tags:
      - Statistics
      summary: Count Endpoints
      description: Count the number of active and disabled endpoints in the environment.
      operationId: v1.statistics.endpoint-count
      parameters:
      - in: query
        name: exclude_svix_play
        description: Exclude endpoints that point to a play.svix.com url from the count
        schema:
          description: Exclude endpoints that point to a play.svix.com url from the count
          type: boolean
          default: true
        style: form
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndpointCountOut'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
      security:
      - HTTPBearer: []
      x-internal: true
  /api/v1/stats/app/{app_id}/attempt:
    get:
      tags:
      - Statistics
      summary: Get App Attempt Stats
      description: Returns application-level statistics on message attempts
      operationId: v1.stats.app-attempts
      parameters:
      - in: query
        name: startDate
        description: Filter the range to data starting from this date.
        schema:
          description: Filter the range to data starting from this date.
          type: string
          format: date-time
          nullable: true
        style: form
      - in: query
        name: endDate
        description: Filter the range to data ending by this date.
        schema:
          description: Filter the range to data ending by this date.
          type: string
          format: date-time
          nullable: true
        style: form
      - in: query
        name: period
        description: The period to aggregate the data by.
        schema:
          description: The period to aggregate the data by.
          $ref: '#/components/schemas/StatisticsPeriod'
          nullable: true
        style: form
      - in: query
        name: event_types
        description: Filter response based on the event type
        schema:
          description: Filter response based on the event type
          type: array
          items:
            description: The event type's name
            type: string
            maxLength: 256
            pattern: ^[a-zA-Z0-9\-_.]+$
            example: user.signup
          uniqueItems: true
          nullable: true
        style: form
      - in: path
        name: app_id
        description: The Application's ID or UID.
        required: true
        schema:
          description: The Application's ID or UID.
          type: string
          maxLength: 256
          minLength: 1
          pattern: ^[a-zA-Z0-9\-_.]+$
          example: unique-identifier
        style: simple
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttemptStatisticsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
      security:
      - HTTPBearer: []
      x-internal: true
components:
  schemas:
    AppUsageStatsOut:
      type: object
      properties:
        unresolvedAppIds:
          description: 'Any app IDs or UIDs received in the request that weren''t found.


            Stats will be produced for all the others.'
          type: array
          items:
            description: The Application's ID or UID.
            type: string
            maxLength: 256
            minLength: 1
            pattern: ^[a-zA-Z0-9\-_.]+$
            example: unique-identifier
          uniqueItems: true
        id:
          description: The QueueBackgroundTask's ID.
          type: string
          maxLength: 33
          minLength: 33
          pattern: ^qtask_[A-Za-z0-9]{27}$
          example: qtask_1srOrx2ZWZBpBUvZwXKQmoEYga2
        status:
          $ref: '#/components/schemas/BackgroundTaskStatus'
        task:
          $ref: '#/components/schemas/BackgroundTaskType'
        updatedAt:
          type: string
          format: date-time
      required:
      - id
      - status
      - task
      - unresolvedAppIds
      - updatedAt
    ValidationError:
      description: Validation errors have their own schema to provide context for invalid requests eg. mismatched types and out of bounds values. There may be any number of these per 422 UNPROCESSABLE ENTITY error.
      type: object
      properties:
        loc:
          description: The location as a [`Vec`] of [`String`]s -- often in the form `["body", "field_name"]`, `["query", "field_name"]`, etc. They may, however, be arbitrarily deep.
          type: array
          items:
            type: string
        msg:
          description: The message accompanying the validation error item.
          type: string
        type:
          description: The type of error, often "type_error" or "value_error", but sometimes with more context like as "value_error.number.not_ge"
          type: string
      required:
      - loc
      - msg
      - type
    HttpErrorOut:
      title: HttpError
      type: object
      properties:
        code:
          type: string
        detail:
          type: string
      required:
      - code
      - detail
    BackgroundTaskType:
      type: string
      enum:
      - endpoint.replay
      - endpoint.recover
      - application.stats
      - message.broadcast
      - sdk.generate
      - event-type.aggregate
      - application.purge_content
      - endpoint.bulk-replay
    AttemptStatisticsData:
      type: object
      properties:
        successCount:
          type: array
          items:
            type: integer
            format: int
          nullable: true
        failureCount:
          type: array
          items:
            type: integer
            format: int
          nullable: true
        canceledCount:
          type: array
          items:
            type: integer
            format: int
          nullable: true
    StatisticsPeriod:
      description: Period length for a statistics data point.
      type: string
      enum:
      - OneDay
      - OneHour
      - FiveMinutes
    AppUsageStatsIn:
      type: object
      properties:
        since:
          type: string
          format: date-time
        until:
          type: string
          format: date-time
        appIds:
          description: 'Specific app IDs or UIDs to aggregate stats for.


            Note that if none of the given IDs or UIDs are resolved, a 422 response will be given.'
          type: array
          items:
            description: The Application's ID or UID.
            type: string
            maxLength: 256
            minLength: 1
            pattern: ^[a-zA-Z0-9\-_.]+$
            example: unique-identifier
          uniqueItems: true
          nullable: true
      required:
      - since
      - until
    AttemptStatisticsResponse:
      type: object
      properties:
        startDate:
          type: string
          format: date-time
        endDate:
          type: string
          format: date-time
        period:
          $ref: '#/components/schemas/StatisticsPeriod'
        data:
          $ref: '#/components/schemas/AttemptStatisticsData'
      required:
      - data
      - endDate
      - period
      - startDate
    BackgroundTaskStatus:
      type: string
      enum:
      - running
      - finished
      - failed
    EndpointCountOut:
      type: object
      properties:
        active:
          type: integer
          format: uint64
          minimum: 0.0
        disabled:
          type: integer
          format: uint64
          minimum: 0.0
      required:
      - active
      - disabled
    HTTPValidationError:
      type: object
      properties:
        detail:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
      required:
      - detail
    AggregateEventTypesOut:
      type: object
      properties:
        id:
          description: The QueueBackgroundTask's ID.
          type: string
          maxLength: 33
          minLength: 33
          pattern: ^qtask_[A-Za-z0-9]{27}$
          example: qtask_1srOrx2ZWZBpBUvZwXKQmoEYga2
        status:
          $ref: '#/components/schemas/BackgroundTaskStatus'
        task:
          $ref: '#/components/schemas/BackgroundTaskType'
        updatedAt:
          type: string
          format: date-time
      required:
      - id
      - status
      - task
      - updatedAt
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
      description: HTTP Bearer token passed in the `Authorization` header
x-tagGroups:
- name: General
  tags:
  - Background Task
  - Environment
- name: Dispatch
  tags:
  - Application
  - Event Type
  - Authentication
  - Endpoint
  - Message
  - Message Attempt
  - Integration
  - Connector
- name: Stream
  tags:
  - Stream
  - Sink
  - Event
  - Stream Event Type
  - Stream Authentication
- name: Ingest
  tags:
  - Ingest Source
  - Ingest Endpoint
- name: Operational Webhooks
  tags:
  - Webhook
  - Webhook Endpoint
- name: Statistics
  tags:
  - Statistics
- name: Utility
  tags:


# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/svix/refs/heads/main/openapi/svix-statistics-api-openapi.yml