LogBrew Volume API

openapi: 3.2.0
info:
  contact:
    email: support@logbrew.co
    name: LogBrew support
    url: https://logbrew.co
  description: 'Send `Authorization: Bearer ` with an account access token or a project key. `logbrew login` signs in and stores an access token; `logbrew projects keys create` makes project keys. A read key reads one project''s telemetry and nothing else. Without the CLI, get an access token with device sign-in (RFC 8628): `POST /api/auth/device` with a form-encoded `client_id`, show the person the `user_code` and `verification_uri`, then poll `POST /api/auth/device/token` until they approve.


    Every error has the same JSON shape: a stable `code`, a readable `error`, and a `next` step that says how to recover. A `429` response carries `Retry-After`.


    Some operations have several response versions. This document describes the newest one, so send the `response_version` it requires. List operations return pages with `pagination=cursor`. Older versions keep their exact shape for clients that already use them.


    To test an integration without touching production data, create a separate project for it: each project has its own keys and data, and the free plan covers it. `load_sample_data` fills a new project with a connected example issue, logs, and trace that never count toward usage, `remove_sample_data` removes exactly those rows, and `send_test_event` checks a key end to end.'
  summary: Read and manage LogBrew projects, issues, logs, traces, actions, metrics, releases, and product analytics.
  title: LogBrew Volume API
  version: '1'
servers:
- description: LogBrew API
  url: https://api.logbrew.co
tags:
- description: Signal counts over time.
  name: Volume
paths:
  /api/telemetry/summary/volume:
    get:
      description: Count logs, issues, traces, actions, and metrics over time. Accepts an account access token or a `read` project key.
      operationId: get_signal_volume
      parameters:
      - description: Optional exact environment filter applied to every included signal.
        in: query
        name: environment
        required: false
        schema:
          type: string
      - description: Optional bucket interval (`auto`, `1m`, `5m`, `15m`, `1h`, `6h`, or `1d`).
        in: query
        name: interval
        required: false
        schema:
          type: string
      - description: Required owned project.
        in: query
        name: project_id
        required: true
        schema:
          format: uuid
          type: string
      - description: Optional exact release filter applied to every included signal.
        in: query
        name: release
        required: false
        schema:
          type: string
      - description: Optional exact service filter applied to every included signal.
        in: query
        name: service_name
        required: false
        schema:
          type: string
      - description: Required inclusive lower bound, as a compact duration or RFC 3339 timestamp.
        in: query
        name: since
        required: true
        schema:
          type: string
      - description: Optional exclusive RFC 3339 upper bound; defaults to the request time.
        in: query
        name: until
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                coverage:
                  count_precision: exact
                  integer_safety: javascript_safe
                  javascript_safe_integer_max: 9007199254740991
                  limitations:
                  - upstream_sampling_unknown
                  max_buckets_per_series: 500
                  output_truncation: not_truncated
                  payload_shape: aggregate_only
                  retention:
                    cutoff: '2026-10-27T12:00:00Z'
                    policy_days: 1
                    window_clipped: false
                  returned_points: 1
                  returned_series: 5
                  sampling:
                    server: not_applied
                    upstream: unknown
                  storage_evaluation: complete
                purpose: string
                query:
                  bucket_alignment: query_relative_utc_half_open
                  bucket_count: 1
                  environment: string
                  interval: string
                  interval_seconds: 1
                  project_id: 0b9f7c4e-2f2a-4a8e-9a65-2d2a7e8f1c11
                  release: string
                  requested_since: '2026-10-27T12:00:00Z'
                  service_name: string
                  since: '2026-10-27T12:00:00Z'
                  until: '2026-10-27T12:00:00Z'
                schema_version: 1
                series:
                - count_unit: issue_occurrences
                  non_empty_buckets: 1
                  peak: 1
                  points:
                  - bucket_end: '2026-10-27T12:00:00Z'
                    bucket_start: '2026-10-27T12:00:00Z'
                    count: 1
                  signal: issues
                  total: 1
              schema:
                $ref: '#/components/schemas/SdkSignalVolumeResponse'
          description: Success.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        default:
          $ref: '#/components/responses/Error'
      security:
      - accessToken: []
      - projectKey:
        - read
      summary: Count logs, issues, traces, actions, and metrics over time
      tags:
      - Volume
  /api/telemetry/summary/volume/combined:
    get:
      description: Count signals over time across several projects. Needs an account access token.
      operationId: get_combined_signal_volume
      parameters:
      - description: Optional exact environment filter applied to every included signal.
        in: query
        name: environment
        required: false
        schema:
          type: string
      - description: Optional bucket interval (`auto`, `1m`, `5m`, `15m`, `1h`, `6h`, or `1d`).
        in: query
        name: interval
        required: false
        schema:
          type: string
      - description: Required comma-separated set of one to fifty readable project IDs.
        in: query
        name: project_ids
        required: true
        schema:
          type: string
      - description: Optional exact release filter applied to every included signal.
        in: query
        name: release
        required: false
        schema:
          type: string
      - description: Optional exact service filter applied to every included signal.
        in: query
        name: service_name
        required: false
        schema:
          type: string
      - description: Required inclusive lower bound, as a compact duration or RFC 3339 timestamp.
        in: query
        name: since
        required: true
        schema:
          type: string
      - description: Optional exclusive RFC 3339 upper bound; defaults to the request time.
        in: query
        name: until
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                coverage:
                  count_precision: exact
                  integer_safety: javascript_safe
                  javascript_safe_integer_max: 9007199254740991
                  limitations:
                  - upstream_sampling_unknown
                  max_buckets_per_series: 500
                  output_truncation: not_truncated
                  payload_shape: aggregate_only
                  retention:
                    cutoff: '2026-10-27T12:00:00Z'
                    policy_days: 1
                    window_clipped: false
                  returned_points: 1
                  returned_series: 5
                  sampling:
                    server: not_applied
                    upstream: unknown
                  storage_evaluation: complete
                purpose: string
                query:
                  bucket_alignment: query_relative_utc_half_open
                  bucket_count: 1
                  environment: string
                  interval: string
                  interval_seconds: 1
                  project_ids:
                  - 0b9f7c4e-2f2a-4a8e-9a65-2d2a7e8f1c11
                  release: string
                  requested_since: '2026-10-27T12:00:00Z'
                  service_name: string
                  since: '2026-10-27T12:00:00Z'
                  until: '2026-10-27T12:00:00Z'
                schema_version: 1
                series:
                - count_unit: issue_occurrences
                  non_empty_buckets: 1
                  peak: 1
                  points:
                  - bucket_end: '2026-10-27T12:00:00Z'
                    bucket_start: '2026-10-27T12:00:00Z'
                    count: 1
                  signal: issues
                  total: 1
              schema:
                $ref: '#/components/schemas/SdkCombinedSignalVolumeResponse'
          description: Success.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        default:
          $ref: '#/components/responses/Error'
      security:
      - accessToken: []
      summary: Count signals over time across several projects
      tags:
      - Volume
components:
  schemas:
    SdkSignalVolumeSamplingResponse:
      description: Sampling qualification for retained counts.
      properties:
        server:
          $ref: '#/components/schemas/SdkSignalVolumeServerSamplingResponse'
          description: Server-side aggregation sampling state.
        upstream:
          $ref: '#/components/schemas/SdkSignalVolumeUpstreamSamplingResponse'
          description: Upstream capture sampling knowledge.
      required:
      - server
      - upstream
      type: object
    SdkSignalVolumeOutputTruncationResponse:
      description: Aggregate output truncation state.
      oneOf:
      - const: not_truncated
        description: No aggregate row or aligned point was clipped by a response limit.
        type: string
    SdkSignalVolumeStorageEvaluationResponse:
      description: Storage evaluation state for the requested retained window.
      oneOf:
      - const: complete
        description: Every matching retained row was evaluated or the request failed.
        type: string
    SdkSignalVolumeServerSamplingResponse:
      description: Backend-side sampling state.
      oneOf:
      - const: not_applied
        description: The aggregate query does not sample stored rows.
        type: string
    SdkSignalVolumeQueryResponse:
      description: Normalized query echoed by the signal-volume response.
      properties:
        bucket_alignment:
          $ref: '#/components/schemas/SdkSignalVolumeBucketAlignment'
          description: Query-relative UTC alignment used by every series.
        bucket_count:
          description: Number of aligned buckets returned per series.
          format: uint64
          maximum: 500
          minimum: 0
          type: integer
        environment:
          description: Optional exact environment filter.
          type:
          - string
          - 'null'
        interval:
          description: Stable effective interval token.
          type: string
        interval_seconds:
          description: Fixed interval width in seconds.
          format: uint64
          minimum: 0
          type: integer
        project_id:
          description: Exact owned project requested.
          format: uuid
          type: string
        release:
          description: Optional exact release filter.
          type:
          - string
          - 'null'
        requested_since:
          description: Original inclusive UTC lower bound before retention policy is applied.
          format: date-time
          type: string
        service_name:
          description: Optional exact service filter.
          type:
          - string
          - 'null'
        since:
          description: Effective inclusive UTC lower bound used for this result.
          format: date-time
          type: string
        until:
          description: Effective exclusive UTC upper bound.
          format: date-time
          type: string
      required:
      - project_id
      - requested_since
      - since
      - until
      - interval
      - interval_seconds
      - bucket_alignment
      - bucket_count
      type: object
    SdkSignalVolumeSeriesResponse:
      description: One independently scalable signal lane.
      properties:
        count_unit:
          $ref: '#/components/schemas/SdkSignalVolumeCountUnit'
          description: Exact semantic unit used by every point and summary count.
        non_empty_buckets:
          description: Number of buckets with at least one matching item.
          format: uint64
          maximum: 500
          minimum: 0
          type: integer
        peak:
          description: Largest retained bucket count.
          format: uint64
          maximum: 9007199254740991
          minimum: 0
          type: integer
        points:
          description: Complete aligned series, including explicit zero buckets.
          items:
            $ref: '#/components/schemas/SdkSignalVolumePointResponse'
          maxItems: 500
          type: array
        signal:
          $ref: '#/components/schemas/SdkSignalVolumeSignal'
          description: Stable signal identity.
        total:
          description: Sum of the mutually exclusive aligned buckets.
          format: uint64
          maximum: 9007199254740991
          minimum: 0
          type: integer
      required:
      - signal
      - count_unit
      - total
      - peak
      - non_empty_buckets
      - points
      type: object
    SdkSignalVolumeBucketAlignment:
      description: Closed alignment semantics shared by every signal lane.
      oneOf:
      - const: query_relative_utc_half_open
        description: 'Buckets begin at the effective lower bound and use inclusive-start, exclusive-end UTC

          boundaries; only the final bucket may be shorter than the selected interval.'
        type: string
    SdkSignalVolumeRetentionResponse:
      description: Retention-policy qualification for the evaluated window.
      properties:
        cutoff:
          description: Evaluated UTC retention cutoff, when a fixed policy exists.
          format: date-time
          type:
          - string
          - 'null'
        policy_days:
          description: Configured retention policy in days, or null when the backend has no fixed policy.
          format: uint64
          minimum: 0
          type:
          - integer
          - 'null'
        window_clipped:
          description: Whether the requested lower bound was clipped to the retention cutoff.
          type: boolean
      required:
      - policy_days
      - window_clipped
      type: object
    SdkSignalVolumeUpstreamSamplingResponse:
      description: Upstream sampling knowledge available to the aggregate query.
      oneOf:
      - const: unknown
        description: SDK or collector sampling performed before ingestion cannot be reconstructed here.
        type: string
    SdkSignalVolumePayloadShapeResponse:
      description: Public response payload shape.
      oneOf:
      - const: aggregate_only
        description: Only counts and bucket boundaries are returned; source telemetry rows are absent.
        type: string
    SdkSignalVolumeCountPrecisionResponse:
      description: Aggregate cardinality precision.
      oneOf:
      - const: exact
        description: Counts use exact distinct aggregation rather than an estimate.
        type: string
    SdkSignalVolumePointResponse:
      description: One aligned, zero-filled aggregate bucket.
      properties:
        bucket_end:
          description: Exclusive UTC bucket end, clipped to the query upper bound.
          format: date-time
          type: string
        bucket_start:
          description: Inclusive UTC bucket start.
          format: date-time
          type: string
        count:
          description: Exact retained count for the lane's declared unit.
          format: uint64
          maximum: 9007199254740991
          minimum: 0
          type: integer
      required:
      - bucket_start
      - bucket_end
      - count
      type: object
    SdkCombinedSignalVolumeResponse:
      description: Complete bounded signal-volume response combined across several projects.
      properties:
        coverage:
          $ref: '#/components/schemas/SdkSignalVolumeCoverageResponse'
          description: Completeness and evidence qualification.
        purpose:
          description: Concise product and machine interpretation.
          type: string
        query:
          $ref: '#/components/schemas/SdkCombinedSignalVolumeQueryResponse'
          description: Normalized query and bucket semantics.
        schema_version:
          description: Exact response schema.
          format: uint8
          maximum: 1
          minimum: 1
          type: integer
        series:
          description: Fixed-order, independently scalable signal lanes.
          items:
            $ref: '#/components/schemas/SdkSignalVolumeSeriesResponse'
          maxItems: 5
          minItems: 5
          type: array
      required:
      - schema_version
      - query
      - purpose
      - series
      - coverage
      type: object
    SdkSignalVolumeResponse:
      description: Complete bounded signal-volume response.
      properties:
        coverage:
          $ref: '#/components/schemas/SdkSignalVolumeCoverageResponse'
          description: Completeness and evidence qualification.
        purpose:
          description: Concise product and machine interpretation.
          type: string
        query:
          $ref: '#/components/schemas/SdkSignalVolumeQueryResponse'
          description: Normalized query and bucket semantics.
        schema_version:
          description: Exact response schema.
          format: uint8
          maximum: 1
          minimum: 1
          type: integer
        series:
          description: Fixed-order, independently scalable signal lanes.
          items:
            $ref: '#/components/schemas/SdkSignalVolumeSeriesResponse'
          maxItems: 5
          minItems: 5
          type: array
      required:
      - schema_version
      - query
      - purpose
      - series
      - coverage
      type: object
    SdkSignalVolumeSignal:
      description: Stable signal lane returned by the aggregate summary.
      oneOf:
      - const: issues
        description: Retained issue occurrences, not grouped issue identities.
        type: string
      - const: logs
        description: Retained log events.
        type: string
      - const: traces
        description: Unique traces attributed to their first retained span inside the selected window.
        type: string
      - const: actions
        description: Retained product-action events.
        type: string
      - const: metrics
        description: Retained metric points.
        type: string
    SdkSignalVolumeIntegerSafetyResponse:
      description: Serialized integer-safety state.
      oneOf:
      - const: javascript_safe
        description: Every serialized count is within JavaScript's exact integer range.
        type: string
    SdkSignalVolumeCountUnit:
      description: Exact counting unit for one signal lane.
      oneOf:
      - const: issue_occurrences
        description: Distinct retained issue-event IDs.
        type: string
      - const: log_events
        description: Distinct retained log-event IDs.
        type: string
      - const: unique_traces_by_first_observed_span
        description: Distinct trace IDs attributed to the first retained span in the selected window.
        type: string
      - const: action_events
        description: Distinct retained action-event IDs.
        type: string
      - const: metric_points
        description: Distinct retained metric-point IDs.
        type: string
    SdkCombinedSignalVolumeQueryResponse:
      description: Normalized query echoed by the combined signal-volume response.
      properties:
        bucket_alignment:
          $ref: '#/components/schemas/SdkSignalVolumeBucketAlignment'
          description: Query-relative UTC alignment used by every series.
        bucket_count:
          description: Number of aligned buckets returned per series.
          format: uint64
          maximum: 500
          minimum: 0
          type: integer
        environment:
          description: Optional exact environment filter.
          type:
          - string
          - 'null'
        interval:
          description: Stable effective interval token.
          type: string
        interval_seconds:
          description: Fixed interval width in seconds.
          format: uint64
          minimum: 0
          type: integer
        project_ids:
          description: Readable projects combined in this result, sorted.
          items:
            format: uuid
            type: string
          type: array
        release:
          description: Optional exact release filter.
          type:
          - string
          - 'null'
        requested_since:
          description: Original inclusive UTC lower bound before retention policy is applied.
          format: date-time
          type: string
        service_name:
          description: Optional exact service filter.
          type:
          - string
          - 'null'
        since:
          description: Effective inclusive UTC lower bound used for this result.
          format: date-time
          type: string
        until:
          description: Effective exclusive UTC upper bound.
          format: date-time
          type: string
      required:
      - project_ids
      - requested_since
      - since
      - until
      - interval
      - interval_seconds
      - bucket_alignment
      - bucket_count
      type: object
    SdkSignalVolumeLimitationResponse:
      description: Stable material limitation codes for localized clients and agents.
      oneOf:
      - const: upstream_sampling_unknown
        description: SDK or collector sampling before ingestion is not represented by stored aggregates.
        type: string
      - const: retention_window_clipped
        description: The requested lower bound preceded the configured retention cutoff.
        type: string
      - const: release_volume_not_included
        description: Releases are omitted until a durable first-seen release index exists.
        type: string
    SdkSignalVolumeCoverageResponse:
      description: Completeness, bounds, retention, and sampling receipt.
      properties:
        count_precision:
          $ref: '#/components/schemas/SdkSignalVolumeCountPrecisionResponse'
          description: Whether aggregate cardinalities are exact or estimated.
        integer_safety:
          $ref: '#/components/schemas/SdkSignalVolumeIntegerSafetyResponse'
          description: Whether serialized counts retain integer precision in JavaScript.
        javascript_safe_integer_max:
          description: Exact inclusive safe-integer ceiling enforced before serialization.
          format: uint64
          maximum: 9007199254740991
          minimum: 9007199254740991
          type: integer
        limitations:
          description: Stable limitations that materially qualify interpretation.
          items:
            $ref: '#/components/schemas/SdkSignalVolumeLimitationResponse'
          type: array
        max_buckets_per_series:
          description: Hard maximum buckets accepted for one lane.
          format: uint64
          maximum: 500
          minimum: 500
          type: integer
        output_truncation:
          $ref: '#/components/schemas/SdkSignalVolumeOutputTruncationResponse'
          description: Whether any aggregate output was clipped by a limit.
        payload_shape:
          $ref: '#/components/schemas/SdkSignalVolumePayloadShapeResponse'
          description: Whether the payload contains aggregate or source-row data.
        retention:
          $ref: '#/components/schemas/SdkSignalVolumeRetentionResponse'
          description: Retention qualification for the effective window.
        returned_points:
          description: Aligned points returned across all lanes.
          format: uint64
          maximum: 2500
          minimum: 0
          type: integer
        returned_series:
          description: Fixed number of expected and returned signal lanes.
          format: uint8
          maximum: 5
          minimum: 5
          type: integer
        sampling:
          $ref: '#/components/schemas/SdkSignalVolumeSamplingResponse'
          description: Sampling qualification for retained counts.
        storage_evaluation:
          $ref: '#/components/schemas/SdkSignalVolumeStorageEvaluationResponse'
          description: Whether all matching retained rows were evaluated.
      required:
      - storage_evaluation
      - output_truncation
      - payload_shape
      - count_precision
      - integer_safety
      - javascript_safe_integer_max
      - returned_series
      - returned_points
      - max_buckets_per_series
      - retention
      - sampling
      - limitations
      type: object
  responses:
    Error:
      content:
        application/json:
          schema:
            properties:
              code:
                description: Stable reason, such as `unauthorized`, `forbidden`, `not_found`, `validation_failed`, `rate_limited`, or `usage_limit_exceeded`.
                type: string
              deleted_at:
                description: When the account was deleted, on `account_recovery_available`.
                type: string
              error:
                description: What went wrong, in words.
                type: string
              limit:
                description: The limit that was reached.
                type: string
              next:
                description: How to recover.
                type: string
              next_action:
                description: The recovery as stable codes.
                properties:
                  code:
                    description: Stable recovery action, such as `sign_in` or `retry_later`.
                    type: string
                  target:
                    description: Where the recovery happens, such as `auth` or `billing`.
                    type: string
                required:
                - code
                - target
                type: object
              recovery_token:
                description: Token for restore_account, on `account_recovery_available`.
                type: string
              reset_at:
                description: When the limit resets, as an RFC 3339 time.
                type: string
              retry_after_seconds:
                description: Seconds to wait, on `rate_limited`.
                minimum: 0
                type: integer
            required:
            - error
            - code
            - next
            - next_action
            type: object
      description: The request failed. `code` names the reason and `next` says how to recover.
    Unauthorized:
      content:
        application/json:
          schema:
            properties:
              code:
                description: Stable reason, such as `unauthorized`, `forbidden`, `not_found`, `validation_failed`, `rate_limited`, or `usage_limit_exceeded`.
                type: string
              deleted_at:
                description: When the account was deleted, on `account_recovery_available`.
                type: string
              error:
                description: What went wrong, in words.
                type: string
              limit:
                description: The limit that was reached.
                type: string
              next:
                description: How to recover.
                type: string
              next_action:
                description: The recovery as stable codes.
                properties:
                  code:
                    description: Stable recovery action, such as `sign_in` or `retry_later`.
                    type: string
                  target:
                    description: Where the recovery happens, such as `auth` or `billing`.
                    type: string
                required:
                - code
                - target
                type: object
              recovery_token:
                description: Token for restore_account, on `account_recovery_available`.
                type: string
              reset_at:
                description: When the limit resets, as an RFC 3339 time.
                type: string
              retry_after_seconds:
                description: Seconds to wait, on `rate_limited`.
                minimum: 0
                type: integer
            required:
            - error
            - code
            - next
            - next_action
            type: object
      description: The credential is missing, expired, or revoked, or this operation does not accept it.
    RateLimited:
      content:
        application/json:
          schema:
            properties:
              code:
                description: Stable reason, such as `unauthorized`, `forbidden`, `not_found`, `validation_failed`, `rate_limited`, or `usage_limit_exceeded`.
                type: string
              deleted_at:
                description: When the account was deleted, on `account_recovery_available`.
                type: string
              error:
                description: What went wrong, in words.
                type: string
              limit:
                description: The limit that was reached.
                type: string
              next:
                description: How to recover.
                type: string
              next_action:
                description: The recovery as stable codes.
                properties:
                  code:
                    description: Stable recovery action, such as `sign_in` or `retry_later`.
                    type: string
                  target:
                    description: Where the recovery happens, such as `auth` or `billing`.
                    type: string
                required:
                - code
                - target
                type: object
              recovery_token:
                description: Token for restore_account, on `account_recovery_available`.
                type: string
              reset_at:
                description: When the limit resets, as an RFC 3339 time.
                type: string
              retry_after_seconds:
                description: Seconds to wait, on `rate_limited`.
                minimum: 0
                type: integer
            required:
            - error
            - code
            - next
            - next_action
            type: object
      description: Too many requests. Wait the `Retry-After` seconds, then retry.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            minimum: 0
            type: integer
  securitySchemes:
    accessToken:
      bearerFormat: JWT
      description: Account access token. It acts as your account in every project you can reach. `logbrew login` creates one; renew it with refresh_access_token before it expires.
      scheme: bearer
      type: http
    projectKey:
      description: 'Project key. A key reaches only its own project and has one kind: `read` keys (prefix `lbw_read_`) read telemetry; `sdk`, `server`, `browser`, and `cli` keys (prefix `lbw_ingest_`) send telemetry; `artifact` keys upload debug files. Each operation''s security requirement lists the kinds it accepts.'
      scheme: bearer
      type: http