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

# Get the agent cost report

> Spend vs cap per agent plus a paged agent x project x task rollup for the period. humanHourlyRate is a what-if input for the ROI columns and is never stored.



## OpenAPI

````yaml https://www.amdital.com/openapi.json get /api/v1/agent-cost-report
openapi: 3.0.0
info:
  title: AmDital API
  description: >-
    AmDital enterprise business operating system API — generated directly from
    the live NestJS controllers and their Zod request/response schemas (see
    apps/api/src/openapi/generate.ts).
  version: 2.0.0
  contact: {}
servers:
  - url: https://api.amdital.com
    description: Production
  - url: http://localhost:8000
    description: Local development
security:
  - bearerAuth: []
tags:
  - name: Health
    description: Liveness/readiness probe. Unauthenticated.
  - name: AuthNext
    description: >-
      Live authentication surface — login, password verification, token refresh,
      session management, MFA, and admin credential resets.
      login/verify-password/refresh are public (the credential exchange itself);
      session/MFA routes require the bearer JWT they issue; admin/* routes are
      internal-key gated, server-to-server only.
  - name: Content
    description: >-
      Generic tenant-scoped CRUD over the 49 allowlisted content/config
      collections (see the `collection` path parameter enum) — the NestJS
      replacement for Payload REST on these collections; response shapes match
      Payload REST so existing consumers work unchanged.
  - name: Activity
    description: >-
      Activity logs and screenshot capture/scoring for the time-tracking desktop
      agent.
  - name: Ai
    description: AMI agents, prompts, and workflows — create, deploy/activate, and manage.
  - name: Calendar
    description: Workspace calendars and calendar events.
  - name: Clients
    description: Client organizations and client contacts.
  - name: Content Admin
    description: >-
      Public reads for roadmap items, testimonials, feature ideas, and
      blog/survey content; write endpoints (create/update/remove, upvote, survey
      responses) require the `x-internal-key`/`x-api-key` server-to-server
      header — these writes are not for third-party API consumers.
  - name: Crm
    description: >-
      Companies, leads, deals, pipelines, products, sequences, sequence
      enrollments, custom field definitions, lead routing rules, and client
      portal tokens. Contacts are documented separately under the Clients tag.
  - name: Docs
    description: >-
      Tenant-internal wiki: doc categories and doc pages (distinct from the
      public docs-site content under Public Content).
  - name: Finance
    description: Invoices, payments, budgets, expenses, and purchase orders.
  - name: Goals
    description: Workspace goals/OKRs.
  - name: Hrms
    description: >-
      Employees, departments, roles, shifts, leave requests, performance
      reviews, payroll runs, compliance records, salary structures/revisions,
      bonuses, arrears, and the per-employee payroll activity feed.
  - name: Integrations
    description: Outbound webhooks and third-party integration tokens.
  - name: Lms
    description: >-
      Learning management: the paginated course list, enrollment/module/lesson
      CRUD, lesson completion, course favorites, and course-category CRUD.
  - name: Marketing
    description: Marketing campaigns, email templates, and marketing assets.
  - name: Public Content
    description: >-
      Fully public, unauthenticated docs/marketing content reads (doc
      categories, doc articles, changelog, FAQs) — paths intentionally match
      Payload REST exactly (no `/v1`, no auth) because apps/docs hardcodes these
      URLs.
  - name: Recruitment
    description: Job postings, applicants, and interviews.
  - name: Reports
    description: Saved report configurations/definitions.
  - name: Report Definitions
    description: >-
      Reusable saved report definitions (name/type/filter-definition/schedule)
      distinct from the one-off generated reports above — includes "run" to
      execute a definition and produce a new report_snapshots row.
  - name: Support
    description: Support channels and tickets, including ticket assignment.
  - name: Time
    description: Time entries/timers and timesheets, including submit/approve/reject.
  - name: Approvals
    description: >-
      Approval requests — read and decide only, by design (no
      create/update/delete).
  - name: Work
    description: Projects, tasks, sprints, chat channels/messages, and work files.
  - name: Notifications
    description: >-
      The signed-in user's in-app notification inbox for the current workspace
      (read-only).
  - name: Workspaces
    description: >-
      Workspaces the signed-in user belongs to (self-service, not scoped to one
      workspace).
  - name: Mcp
    description: >-
      Model Context Protocol server (stateless Streamable HTTP) — the JSON-RPC
      2.0 endpoint (POST, authenticated by a workspace API key or auth-next
      JWT), a public human-readable descriptor at `/info` (GET), and
      spec-mandated 405s for GET/DELETE at the bare endpoint (no SSE stream, no
      sessions).
  - name: Mcp OAuth
    description: >-
      Consent screen backing (read/decide a pending MCP OAuth authorization) and
      the workspace's connected-AI-tool grants (list/revoke). Bearer JWT
      required.
  - name: Metrics
    description: >-
      Prometheus text-format scrape endpoint, authenticated by its own static
      scrape token (not a user JWT).
  - name: Privacy
    description: >-
      GDPR self-service for the signed-in user (export of their personal data,
      irreversible account erasure) and workspace-admin export/erasure of an
      external help-desk requester by email. Bearer JWT required; impersonation
      tokens are refused.
  - name: Internal
    description: >-
      Server-to-server endpoints for AmDital's own apps (trusted Origin + proxy
      secret). Not for third-party API consumers.
paths:
  /api/v1/agent-cost-report:
    get:
      tags:
        - Agent Budgets
      summary: Get the agent cost report
      description: >-
        Spend vs cap per agent plus a paged agent x project x task rollup for
        the period. humanHourlyRate is a what-if input for the ROI columns and
        is never stored.
      operationId: AgentBudgetsController_getCostReport
      parameters:
        - name: period
          in: query
          required: false
          schema:
            type: string
            enum:
              - month
              - last_month
              - last_30_days
              - last_90_days
            default: month
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: humanHourlyRate
          in: query
          required: false
          schema:
            type: number
            nullable: true
            minimum: 0
            maximum: 100000
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - period
                      - totals
                      - agents
                      - tasks
                      - roi
                    properties:
                      period:
                        type: object
                        required:
                          - key
                          - from
                          - to
                        description: Half-open UTC range [from, to).
                        properties:
                          key:
                            type: string
                            enum:
                              - month
                              - last_month
                              - last_30_days
                              - last_90_days
                          from:
                            type: string
                            format: date-time
                          to:
                            type: string
                            format: date-time
                      totals:
                        type: object
                        required:
                          - cost
                          - tokens
                          - runs
                          - unpricedRuns
                        properties:
                          cost:
                            type: number
                          tokens:
                            type: string
                            pattern: ^[0-9]+$
                            description: int64 token count as an exact decimal string.
                          runs:
                            type: integer
                          unpricedRuns:
                            type: integer
                      agents:
                        type: array
                        description: >-
                          Spend vs cap per agent: every non-terminated agent,
                          terminated agents with spend in the period, and agent
                          profiles with spend but no agent record (agentName
                          "Agent", caps null).
                        items:
                          type: object
                          required:
                            - agentId
                            - agentName
                            - status
                            - monthlyCostCap
                            - monthlyTokenCap
                            - cycleSpend
                            - cycleTokens
                            - usagePercentCost
                            - usagePercentTokens
                            - periodCost
                            - periodTokens
                            - periodRuns
                            - unpricedRuns
                          properties:
                            agentId:
                              type: string
                              format: uuid
                            agentName:
                              type: string
                            status:
                              type: string
                              nullable: true
                            monthlyCostCap:
                              type: number
                              nullable: true
                            monthlyTokenCap:
                              type: string
                              pattern: ^[0-9]+$
                              description: int64 token count as an exact decimal string.
                              nullable: true
                            cycleSpend:
                              type: number
                              description: >-
                                Enforcement counter for the budget cycle, not
                                the report period.
                            cycleTokens:
                              type: string
                              pattern: ^[0-9]+$
                              description: int64 token count as an exact decimal string.
                            usagePercentCost:
                              type: number
                              nullable: true
                            usagePercentTokens:
                              type: number
                              nullable: true
                            periodCost:
                              type: number
                            periodTokens:
                              type: string
                              pattern: ^[0-9]+$
                              description: int64 token count as an exact decimal string.
                            periodRuns:
                              type: integer
                            unpricedRuns:
                              type: integer
                              description: >-
                                Runs on a model with no known price: their cost
                                is unknown, not zero.
                      tasks:
                        type: object
                        required:
                          - rows
                          - page
                          - limit
                          - total
                        properties:
                          rows:
                            type: array
                            items:
                              type: object
                              required:
                                - agentId
                                - agentName
                                - projectId
                                - projectName
                                - taskId
                                - taskTitle
                                - cost
                                - tokens
                                - runs
                                - unpricedRuns
                              properties:
                                agentId:
                                  type: string
                                agentName:
                                  type: string
                                projectId:
                                  type: string
                                  nullable: true
                                  format: uuid
                                projectName:
                                  type: string
                                  nullable: true
                                taskId:
                                  type: string
                                  nullable: true
                                  format: uuid
                                taskTitle:
                                  type: string
                                  nullable: true
                                cost:
                                  type: number
                                tokens:
                                  type: string
                                  pattern: ^[0-9]+$
                                  description: >-
                                    int64 token count as an exact decimal
                                    string.
                                runs:
                                  type: integer
                                unpricedRuns:
                                  type: integer
                                agentHours:
                                  type: number
                                  description: >-
                                    Present only when agent timesheet data
                                    exists in the workspace.
                                humanEquivalentCost:
                                  type: number
                                  description: >-
                                    Present only with a humanHourlyRate and
                                    agent hours: hours x rate.
                                netSaving:
                                  type: number
                                  description: >-
                                    humanEquivalentCost - cost; positive means
                                    the agent was cheaper.
                          page:
                            type: integer
                          limit:
                            type: integer
                          total:
                            type: integer
                      roi:
                        type: object
                        required:
                          - available
                          - humanHourlyRate
                        properties:
                          available:
                            type: boolean
                          humanHourlyRate:
                            type: number
                            nullable: true
        '400':
          description: Invalid query
        '401':
          description: Missing or invalid authorization
        '403':
          description: >-
            Caller lacks ai.agents.update.workspace or
            finance.amounts.view.workspace
components:
  securitySchemes:
    bearerAuth:
      scheme: bearer
      bearerFormat: JWT
      type: http

````

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