Parcha Cost Analytics API

openapi: 3.0.0
info:
  title: Parcha Admin Cost Analytics API
  version: 1.0.0
  description: API for managing Parcha jobs and checks
servers:
- url: https://api.parcha.ai/api/v1
  description: Agent Hub API server
- url: https://demo.parcha.ai/api/v1
  description: Sandbox API server
- url: https://us1.parcha.ai/api/v1
  description: Legacy API server
- url: http://{your-company-domain}.parcha.ai/api/v1
  description: Custom Enterpris server (your company's API server)
security:
- bearerAuth: []
tags:
- name: Cost Analytics
paths:
  /admin/cost-analytics/summary:
    get:
      tags:
      - Cost Analytics
      summary: Get Cost Summary
      description: "Get overall cost summary.\n\nArgs:\n    time_range: Time range (1d, 7d, 30d, 90d)\n    current_user: Admin user (enforced)\n\nReturns:\n    Cost summary with totals by resource type"
      operationId: get_cost_summary_admin_cost_analytics_summary_get
      parameters:
      - name: time_range
        in: query
        required: false
        schema:
          type: string
          default: 7d
          title: Time Range
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CostSummaryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /admin/cost-analytics/by-resource:
    get:
      tags:
      - Cost Analytics
      summary: Get Costs By Resource
      description: "Get costs grouped by resource type and provider.\n\nArgs:\n    time_range: Time range (1d, 7d, 30d, 90d)\n    current_user: Admin user (enforced)\n\nReturns:\n    Cost breakdown by resource"
      operationId: get_costs_by_resource_admin_cost_analytics_by_resource_get
      parameters:
      - name: time_range
        in: query
        required: false
        schema:
          type: string
          default: 7d
          title: Time Range
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CostByResourceResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /admin/cost-analytics/timeline:
    get:
      tags:
      - Cost Analytics
      summary: Get Cost Timeline
      description: "Get cost timeline data.\n\nArgs:\n    time_range: Time range (1d, 7d, 30d, 90d)\n    granularity: Time granularity (hourly, daily)\n    current_user: Admin user (enforced)\n\nReturns:\n    Timeline data for charting"
      operationId: get_cost_timeline_admin_cost_analytics_timeline_get
      parameters:
      - name: time_range
        in: query
        required: false
        schema:
          type: string
          default: 7d
          title: Time Range
      - name: granularity
        in: query
        required: false
        schema:
          type: string
          default: hourly
          title: Granularity
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CostTimelineResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /admin/cost-analytics/by-agent:
    get:
      tags:
      - Cost Analytics
      summary: Get Cost By Agent
      description: "Get costs grouped by agent.\n\nArgs:\n    time_range: Time range (1d, 7d, 30d, 90d)\n\nReturns:\n    Costs broken down by agent_key"
      operationId: get_cost_by_agent_admin_cost_analytics_by_agent_get
      parameters:
      - name: time_range
        in: query
        required: false
        schema:
          type: string
          default: 7d
          title: Time Range
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CostByAgentResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /admin/cost-analytics/by-tool:
    get:
      tags:
      - Cost Analytics
      summary: Get Cost By Tool
      description: "Get costs grouped by tool/check.\n\nArgs:\n    time_range: Time range (1d, 7d, 30d, 90d)\n\nReturns:\n    Costs broken down by tool_id (actual tool/loader that generated the cost)"
      operationId: get_cost_by_tool_admin_cost_analytics_by_tool_get
      parameters:
      - name: time_range
        in: query
        required: false
        schema:
          type: string
          default: 7d
          title: Time Range
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CostByToolResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ResourceCostBreakdown:
      properties:
        resource_type:
          type: string
          title: Resource Type
          description: Resource type (llm, scraping, etc.)
        resource_provider:
          type: string
          title: Resource Provider
          description: Provider name
        event_count:
          type: integer
          title: Event Count
          description: Number of events
        total_cost_usd:
          type: number
          title: Total Cost Usd
          description: Total cost in USD
        percentage:
          type: number
          title: Percentage
          description: Percentage of total cost
      type: object
      required:
      - resource_type
      - resource_provider
      - event_count
      - total_cost_usd
      - percentage
      title: ResourceCostBreakdown
      description: Cost breakdown for a specific resource.
    CostByResourceResponse:
      properties:
        resources:
          items:
            $ref: '#/components/schemas/ResourceCostBreakdown'
          type: array
          title: Resources
          description: Resource breakdown
        total_cost_usd:
          type: number
          title: Total Cost Usd
          description: Total cost across all resources
      type: object
      required:
      - resources
      - total_cost_usd
      title: CostByResourceResponse
      description: Costs grouped by resource type and provider.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    CostByToolResponse:
      properties:
        tools:
          items:
            $ref: '#/components/schemas/ToolCostBreakdown'
          type: array
          title: Tools
          description: Tool breakdown
        total_cost_usd:
          type: number
          title: Total Cost Usd
          description: Total cost across all tools
      type: object
      required:
      - tools
      - total_cost_usd
      title: CostByToolResponse
      description: Costs grouped by tool/check.
    ToolCostBreakdown:
      properties:
        command_id:
          type: string
          title: Command Id
          description: Tool/check ID (e.g., 'grep.web_presence')
        agent_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Key
          description: Agent this tool belongs to
        total_cost_usd:
          type: number
          title: Total Cost Usd
          description: Total cost for this tool
        llm_cost_usd:
          type: number
          title: Llm Cost Usd
          description: LLM cost
          default: 0.0
        scraping_cost_usd:
          type: number
          title: Scraping Cost Usd
          description: Scraping cost
          default: 0.0
        event_count:
          type: integer
          title: Event Count
          description: Number of cost events
        avg_cost_per_call:
          type: number
          title: Avg Cost Per Call
          description: Average cost per tool call
        percentage:
          type: number
          title: Percentage
          description: Percentage of total cost
      type: object
      required:
      - command_id
      - total_cost_usd
      - event_count
      - avg_cost_per_call
      - percentage
      title: ToolCostBreakdown
      description: Cost breakdown for a specific tool/check.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AgentCostBreakdown:
      properties:
        agent_key:
          type: string
          title: Agent Key
          description: Agent key (e.g., 'kyb-v1')
        total_cost_usd:
          type: number
          title: Total Cost Usd
          description: Total cost for this agent
        llm_cost_usd:
          type: number
          title: Llm Cost Usd
          description: LLM cost
          default: 0.0
        scraping_cost_usd:
          type: number
          title: Scraping Cost Usd
          description: Scraping cost
          default: 0.0
        event_count:
          type: integer
          title: Event Count
          description: Number of cost events
        job_count:
          type: integer
          title: Job Count
          description: Number of unique jobs (agent runs)
        avg_cost_per_run:
          type: number
          title: Avg Cost Per Run
          description: Average cost per agent run
        percentage:
          type: number
          title: Percentage
          description: Percentage of total cost
      type: object
      required:
      - agent_key
      - total_cost_usd
      - event_count
      - job_count
      - avg_cost_per_run
      - percentage
      title: AgentCostBreakdown
      description: Cost breakdown for a specific agent.
    TimelineDataPoint:
      properties:
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp
        cost_usd:
          type: number
          title: Cost Usd
          description: Cost at this time
        event_count:
          type: integer
          title: Event Count
          description: Number of events
        llm_cost_usd:
          type: number
          title: Llm Cost Usd
          description: LLM cost
          default: 0.0
        scraping_cost_usd:
          type: number
          title: Scraping Cost Usd
          description: Scraping cost
          default: 0.0
      type: object
      required:
      - timestamp
      - cost_usd
      - event_count
      title: TimelineDataPoint
      description: Single point in cost timeline.
    CostSummaryResponse:
      properties:
        total_cost_usd:
          type: number
          title: Total Cost Usd
          description: Total cost in USD
        total_events:
          type: integer
          title: Total Events
          description: Total number of cost events
        llm_cost_usd:
          type: number
          title: Llm Cost Usd
          description: Total LLM costs
          default: 0.0
        scraping_cost_usd:
          type: number
          title: Scraping Cost Usd
          description: Total scraping costs
          default: 0.0
        ocr_cost_usd:
          type: number
          title: Ocr Cost Usd
          description: Total OCR costs
          default: 0.0
        storage_cost_usd:
          type: number
          title: Storage Cost Usd
          description: Total storage costs
          default: 0.0
        llm_events:
          type: integer
          title: Llm Events
          description: Number of LLM events
          default: 0
        scraping_events:
          type: integer
          title: Scraping Events
          description: Number of scraping events
          default: 0
        total_tokens:
          type: integer
          title: Total Tokens
          description: Total tokens (LLM only)
          default: 0
        time_range:
          type: string
          title: Time Range
          description: Time range queried (e.g., '7d')
      type: object
      required:
      - total_cost_usd
      - total_events
      - time_range
      title: CostSummaryResponse
      description: Overall cost summary.
    CostTimelineResponse:
      properties:
        timeline:
          items:
            $ref: '#/components/schemas/TimelineDataPoint'
          type: array
          title: Timeline
          description: Timeline data points
        granularity:
          type: string
          title: Granularity
          description: Time granularity (hourly, daily)
        total_cost_usd:
          type: number
          title: Total Cost Usd
          description: Total cost in period
      type: object
      required:
      - timeline
      - granularity
      - total_cost_usd
      title: CostTimelineResponse
      description: Cost timeline data.
    CostByAgentResponse:
      properties:
        agents:
          items:
            $ref: '#/components/schemas/AgentCostBreakdown'
          type: array
          title: Agents
          description: Agent breakdown
        total_cost_usd:
          type: number
          title: Total Cost Usd
          description: Total cost across all agents
      type: object
      required:
      - agents
      - total_cost_usd
      title: CostByAgentResponse
      description: Costs grouped by agent.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key obtained from your Parcha account settings. Include as Bearer token in the Authorization header.