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

# Show spending per category against normal

> Net spending per category in a period, compared with each category's normal. For a finished period, normal is net spending over up to a year before the period, scaled to the period length. An unfinished period (in_progress) is cut to today and compared with the average of same-length windows starting on the corresponding date in each of up to 12 earlier months, counting only complete windows inside the available baseline. The data behind the Reports section "Spending vs normal". Uses the authenticated user's finance accounts and Sure reporting rules. Experimental: the section is a preview feature, and how normal is defined may still change.




## OpenAPI

````yaml /openapi.yaml get /api/v1/spending_vs_normal
openapi: 3.0.3
info:
  title: Sure API
  version: v1
  description: OpenAPI documentation generated from executable request specs.
servers:
  - url: https://app.sure.am
    description: Production
  - url: http://localhost:3000
    description: Local development
security: []
paths:
  /api/v1/spending_vs_normal:
    get:
      tags:
        - Reports
      summary: Show spending per category against normal
      description: >
        Net spending per category in a period, compared with each category's
        normal. For a finished period, normal is net spending over up to a year
        before the period, scaled to the period length. An unfinished period
        (in_progress) is cut to today and compared with the average of
        same-length windows starting on the corresponding date in each of up to
        12 earlier months, counting only complete windows inside the available
        baseline. The data behind the Reports section "Spending vs normal". Uses
        the authenticated user's finance accounts and Sure reporting rules.
        Experimental: the section is a preview feature, and how normal is
        defined may still change.
      parameters:
        - name: start_date
          in: query
          required: false
          schema:
            type: string
            format: date
          description: >-
            Inclusive ISO date. Requires end_date; both omitted means the
            current month to date.
        - name: end_date
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Inclusive ISO date at or after start_date.
      responses:
        '200':
          description: comparison returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpendingVsNormal'
        '401':
          description: unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: invalid period
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - apiKeyAuth: []
        - oauth2:
            - read
        - oauth2:
            - read_write
components:
  schemas:
    SpendingVsNormal:
      type: object
      required:
        - currency
        - period
        - in_progress
        - baseline_period
        - comparable
        - total
        - normal_total
        - categories
      properties:
        currency:
          type: string
        period:
          $ref: '#/components/schemas/FinancialPeriod'
        in_progress:
          type: boolean
          description: >
            The period has not ended: it is cut to today, and normal is the
            average of same-length windows starting on the corresponding date in
            each of up to 12 earlier months.
        baseline_period:
          type: object
          nullable: true
          required:
            - start_date
            - end_date
          properties:
            start_date:
              type: string
              format: date
            end_date:
              type: string
              format: date
          description: >-
            Up to a year before the period, starting no earlier than the first
            non-pending, non-excluded transaction in eligible accounts after
            transaction-kind exclusions. Null with under 28 days of eligible
            history before the period.
        comparable:
          type: boolean
          description: False when there is not enough history to compute a normal.
        total:
          type: string
          description: Net spending total across all categories in the period.
        normal_total:
          type: string
          nullable: true
          description: Sum of each category's normal. Null when not comparable.
        categories:
          type: array
          items:
            $ref: '#/components/schemas/SpendingVsNormalCategory'
          description: Parent categories, largest total first.
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
        message:
          type: string
          nullable: true
        details:
          oneOf:
            - type: array
              items:
                type: string
            - type: object
          nullable: true
        errors:
          type: array
          items:
            type: string
          nullable: true
          description: >-
            Validation error messages (alternative to details used by trades,
            valuations, etc.)
    FinancialPeriod:
      type: object
      required:
        - start_date
        - end_date
      properties:
        start_date:
          type: string
          format: date
        end_date:
          type: string
          format: date
    SpendingVsNormalCategory:
      type: object
      required:
        - id
        - name
        - color
        - filter_value
        - total
        - normal
        - change
        - ratio
      properties:
        id:
          type: string
          format: uuid
          nullable: true
          description: >-
            Null for the synthetic Uncategorized category. A parent's own
            spending is listed among its subcategories with the parent's id.
        name:
          type: string
        color:
          type: string
          nullable: true
        filter_value:
          type: string
          description: Value for the transactions category filter.
        total:
          type: string
          description: Net spending in the period (expense minus refunds), at least zero.
        normal:
          type: string
          nullable: true
          description: >
            Finished period: net spending over the baseline period, scaled to
            the period length. Unfinished period (in_progress): average net
            spending over the same number of days from earlier month starts.
            Null without enough history.
        change:
          type: string
          nullable: true
          description: total minus normal.
        ratio:
          type: string
          nullable: true
          description: >-
            Fractional change against normal (0.5 = 50% more). Null without a
            positive normal.
        direct:
          type: boolean
          description: >
            Present on subcategories only: true for the parent's own spending,
            booked on the parent rather than a subcategory.
        subcategories:
          type: array
          items:
            $ref: '#/components/schemas/SpendingVsNormalCategory'
          description: Present on parent categories only; adds up to the parent total.
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      name: X-Api-Key
      in: header
      description: API key for authentication. Generate one from your account settings.
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          scopes:
            read: Read access
            read_write: Read and write access

````

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