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

# Get the event usage

> The workspace's events this period against its plan's limit: what is used, what is left, and when the count resets. The figures are the Billing page's. It answers while the workspace is locked or has no plan, when every other route answers 403. The request limits are separate, in the `RateLimit-*` headers.



## OpenAPI

````yaml https://api.highseat.com/v1/openapi.json get /usage
openapi: 3.1.1
info:
  title: Highseat Stats API
  version: 1.0.0
  description: >-
    Read-only access to the same figures the dashboard shows.


    Authentication, limits and the shape of every response:
    https://highseat.com/docs/api.
  license:
    name: Proprietary
servers:
  - url: https://api.highseat.com/v1
security:
  - bearerAuth: []
paths:
  /usage:
    get:
      tags:
        - Usage
      summary: Get the event usage
      description: >-
        The workspace's events this period against its plan's limit: what is
        used, what is left, and when the count resets. The figures are the
        Billing page's. It answers while the workspace is locked or has no plan,
        when every other route answers 403. The request limits are separate, in
        the `RateLimit-*` headers.
      operationId: usage
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      period:
                        type: object
                        properties:
                          start:
                            type: string
                            format: date-time
                            x-native-type: date
                            description: When the period began, at midnight UTC.
                          end:
                            type: string
                            format: date-time
                            x-native-type: date
                            description: >-
                              When the period ends and the count starts again
                              from 0.
                        required:
                          - start
                          - end
                        description: >-
                          The period being counted: a paid plan's billing month,
                          a trial, or a calendar month.
                      plan:
                        anyOf:
                          - enum:
                              - 10k
                              - 25k
                              - 50k
                              - 100k
                              - 200k
                              - 500k
                              - 1m
                              - 2m
                              - 5m
                              - 10m
                              - 20m
                              - 50m
                            type: string
                          - type: 'null'
                        description: >-
                          The tier the usage is metered against. Null during a
                          trial or without a plan.
                      limit:
                        anyOf:
                          - type: integer
                            minimum: -9007199254740991
                            maximum: 9007199254740991
                          - type: 'null'
                        description: >-
                          The events the plan includes a period. Null when
                          nothing limits the usage.
                      events:
                        type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                        description: >-
                          The events the workspace stored this period, across
                          all its sites, deleted ones included.
                      remaining:
                        anyOf:
                          - type: integer
                            minimum: -9007199254740991
                            maximum: 9007199254740991
                          - type: 'null'
                        description: >-
                          The events left before `limit`, never below 0. Null
                          without a limit.
                      overLimitAt:
                        anyOf:
                          - type: integer
                            minimum: -9007199254740991
                            maximum: 9007199254740991
                          - type: 'null'
                        description: >-
                          The event count past which the period is over: 110% of
                          `limit`. Null without a limit.
                      projected:
                        type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                        description: >-
                          The events the period ends with at its pace so far. A
                          trial projects a month at its pace.
                      status:
                        enum:
                          - under
                          - near
                          - over
                          - lock-notice
                          - locked
                        type: string
                        description: >-
                          Where this period's events stand against the limit. A
                          period counts as over only past `overLimitAt`, 110% of
                          the limit: the margin a busy month may use at no
                          charge. `under`: below 80% of the limit, or no limit
                          at all. `near`: from 80% up to `overLimitAt`. `over`:
                          past `overLimitAt` for the first period in a row;
                          nothing closes, and the reports keep answering.
                          `lock-notice`: a second period in a row past it, so
                          the reports lock 7 days after it passed, at `lockAt`,
                          unless the workspace moves to a larger plan. `locked`:
                          the dashboards and every other API route answer 403
                          until a period ends under `overLimitAt` or a larger
                          plan covers the usage. Events are still collected in
                          every status.
                      lockAt:
                        anyOf:
                          - type: string
                            format: date-time
                            x-native-type: date
                          - type: 'null'
                        description: >-
                          When the reports lock, or when they locked. Set only
                          for `lock-notice` and `locked`.
                      trial:
                        anyOf:
                          - type: object
                            properties:
                              day:
                                type: integer
                                minimum: -9007199254740991
                                maximum: 9007199254740991
                                description: The trial's current day, from 1.
                              days:
                                type: integer
                                minimum: -9007199254740991
                                maximum: 9007199254740991
                                description: The trial's length in days.
                            required:
                              - day
                              - days
                          - type: 'null'
                        description: >-
                          The running trial, which has no limit. Null outside a
                          trial.
                      sites:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            name:
                              type: string
                            domain:
                              type: string
                              description: >-
                                The site's hostname, which also names it in a
                                path.
                            events:
                              type: integer
                              minimum: -9007199254740991
                              maximum: 9007199254740991
                              description: The events the site stored this period.
                          required:
                            - id
                            - name
                            - domain
                            - events
                        description: >-
                          The sites the API key reaches, busiest first. A key
                          limited to some sites lists only those, while `events`
                          stays the workspace's total.
                    required:
                      - period
                      - plan
                      - limit
                      - events
                      - remaining
                      - overLimitAt
                      - projected
                      - status
                      - lockAt
                      - trial
                      - sites
                required:
                  - data
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '503':
          $ref: '#/components/responses/Error503'
components:
  headers:
    RateLimit-Limit:
      description: Calls the key may make in the window.
      schema:
        type: integer
    RateLimit-Remaining:
      description: Calls left in the current window.
      schema:
        type: integer
    RateLimit-Reset:
      description: Seconds until the window reopens.
      schema:
        type: integer
    RateLimit-Policy:
      description: >-
        The quota and window, as the IETF draft writes it:
        "hourly";q=600;w=3600.
      schema:
        type: string
    RateLimit:
      description: >-
        The remaining budget, as the IETF draft writes it:
        "hourly";r=599;t=3540.
      schema:
        type: string
    Retry-After:
      description: Seconds to wait before the next call.
      schema:
        type: integer
  responses:
    Error400:
      description: 'The request is malformed: BAD_REQUEST, INVALID_FILTER or INVALID_CURSOR.'
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error401:
      description: 'No API key, or one that is not valid: UNAUTHORIZED.'
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error403:
      description: 'The workspace''s reports are closed until it pays: FORBIDDEN.'
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error404:
      description: 'The site, the funnel or the route does not exist: NOT_FOUND.'
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error422:
      description: 'The report ran into the time cap; try a shorter range: QUERY_TIMEOUT.'
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error429:
      description: >-
        The key has used its hourly budget (RATE_LIMITED), or its workspace
        already runs as many calls at once as it may
        (TOO_MANY_CONCURRENT_REQUESTS).
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error503:
      description: 'The server is busy; retry in a moment: SERVICE_UNAVAILABLE.'
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: >-
                Stable and machine-readable: BAD_REQUEST, INVALID_FILTER,
                INVALID_CURSOR, UNAUTHORIZED, FORBIDDEN, NOT_FOUND,
                QUERY_TIMEOUT, RATE_LIMITED, TOO_MANY_CONCURRENT_REQUESTS,
                SERVICE_UNAVAILABLE or INTERNAL_SERVER_ERROR.
            message:
              type: string
              description: What went wrong, written for a person.
            issues:
              type: array
              items:
                type: object
                properties:
                  path:
                    type: array
                    items:
                      anyOf:
                        - type: string
                        - type: number
                    description: >-
                      The parameter at fault, e.g. ['filter', 1] for the second
                      filter.
                  message:
                    type: string
                required:
                  - path
                  - message
              description: One entry per invalid parameter.
          required:
            - code
            - message
      required:
        - error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.