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

# Usage Analytics

> Comprehensive analytics endpoint (Cost Explorer).

**Required Role:** VIEWER or higher

Returns aggregate metrics, time-series data, top errors, and per-task breakdown
for the selected date range.



## OpenAPI

````yaml GET /v1/teams/{team_id}/usage/analytics
openapi: 3.1.0
info:
  title: Data Raven API
  description: Cloud-to-cloud data transfer platform powered by RClone
  version: 0.5.0
servers: []
security: []
paths:
  /v1/teams/{team_id}/usage/analytics:
    get:
      tags:
        - Usage
      summary: Get Team Analytics
      description: >-
        Comprehensive analytics endpoint.


        **Required Role:** VIEWER or higher


        Returns aggregate metrics, time-series data, top errors, and per-task
        breakdown

        for the selected date range.
      operationId: get_team_analytics_v1_teams__team_id__usage_analytics_get
      parameters:
        - name: team_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Team Id
        - name: start_date
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date
              - type: 'null'
            description: Start date (YYYY-MM-DD)
            title: Start Date
          description: Start date (YYYY-MM-DD)
        - name: end_date
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date
              - type: 'null'
            description: End date (YYYY-MM-DD)
            title: End Date
          description: End date (YYYY-MM-DD)
        - name: range
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: 'Quick pick: mtd, 3m, 6m, 1y'
            title: Range
          description: 'Quick pick: mtd, 3m, 6m, 1y'
        - name: group_by
          in: query
          required: false
          schema:
            type: string
            description: 'Grouping: day, week, month'
            default: day
            title: Group By
          description: 'Grouping: day, week, month'
        - name: task_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: uuid
              - type: 'null'
            description: Filter to a specific task
            title: Task Id
          description: Filter to a specific task
        - name: status
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Filter by execution status
            title: Status
          description: Filter by execution status
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    AnalyticsResponse:
      properties:
        team_id:
          type: string
          title: Team Id
        start_date:
          type: string
          title: Start Date
          description: Effective start date (YYYY-MM-DD)
        end_date:
          type: string
          title: End Date
          description: Effective end date (YYYY-MM-DD)
        group_by:
          type: string
          title: Group By
          description: 'Grouping used: day | week | month'
        summary:
          $ref: '#/components/schemas/AnalyticsSummary'
        time_series:
          items:
            $ref: '#/components/schemas/TimeSeriesBucket'
          type: array
          title: Time Series
        top_errors:
          items:
            $ref: '#/components/schemas/TaskErrorSummary'
          type: array
          title: Top Errors
        task_breakdown:
          items:
            $ref: '#/components/schemas/TaskBreakdown'
          type: array
          title: Task Breakdown
      type: object
      required:
        - team_id
        - start_date
        - end_date
        - group_by
        - summary
        - time_series
        - top_errors
        - task_breakdown
      title: AnalyticsResponse
      description: Full analytics response for the usage analytics dashboard.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AnalyticsSummary:
      properties:
        total_executions:
          type: integer
          title: Total Executions
          description: Total executions in period
        completed:
          type: integer
          title: Completed
          description: Completed executions
        failed:
          type: integer
          title: Failed
          description: Failed executions
        cancelled:
          type: integer
          title: Cancelled
          description: Cancelled executions
        manual:
          type: integer
          title: Manual
          description: Manually triggered executions
        scheduled:
          type: integer
          title: Scheduled
          description: Cron-scheduled executions
        api:
          type: integer
          title: Api
          description: API-triggered executions
        error_rate:
          type: number
          title: Error Rate
          description: Failure rate (0.0-1.0)
        total_files_transferred:
          type: integer
          title: Total Files Transferred
          description: Sum of stats.transfers
        total_files_deleted:
          type: integer
          title: Total Files Deleted
          description: Sum of stats.deletes
        total_checks:
          type: integer
          title: Total Checks
          description: Sum of stats.totalChecks
        total_bytes_transferred:
          type: integer
          title: Total Bytes Transferred
          description: Sum of stats.bytes
        avg_duration_seconds:
          anyOf:
            - type: number
            - type: 'null'
          title: Avg Duration Seconds
          description: Average duration of completed executions
      type: object
      required:
        - total_executions
        - completed
        - failed
        - cancelled
        - manual
        - scheduled
        - api
        - error_rate
        - total_files_transferred
        - total_files_deleted
        - total_checks
        - total_bytes_transferred
      title: AnalyticsSummary
      description: Aggregate metrics over a date range.
    TimeSeriesBucket:
      properties:
        period:
          type: string
          title: Period
          description: Period label (YYYY-MM-DD, YYYY-Www, or YYYY-MM)
        executions:
          type: integer
          title: Executions
          default: 0
        completed:
          type: integer
          title: Completed
          default: 0
        failed:
          type: integer
          title: Failed
          default: 0
        manual:
          type: integer
          title: Manual
          default: 0
        scheduled:
          type: integer
          title: Scheduled
          default: 0
        bytes_transferred:
          type: integer
          title: Bytes Transferred
          default: 0
        files_transferred:
          type: integer
          title: Files Transferred
          default: 0
        files_deleted:
          type: integer
          title: Files Deleted
          default: 0
        files_checked:
          type: integer
          title: Files Checked
          default: 0
        files_renamed:
          type: integer
          title: Files Renamed
          default: 0
        errors:
          type: integer
          title: Errors
          description: Sum of stats.errors (rclone-level errors)
          default: 0
      type: object
      required:
        - period
      title: TimeSeriesBucket
      description: One time-series data point (day, week, or month).
    TaskErrorSummary:
      properties:
        task_id:
          type: string
          title: Task Id
        task_name:
          type: string
          title: Task Name
        error_count:
          type: integer
          title: Error Count
        total_executions:
          type: integer
          title: Total Executions
        error_rate:
          type: number
          title: Error Rate
      type: object
      required:
        - task_id
        - task_name
        - error_count
        - total_executions
        - error_rate
      title: TaskErrorSummary
      description: A task ranked by failure count.
    TaskBreakdown:
      properties:
        task_id:
          type: string
          title: Task Id
        task_name:
          type: string
          title: Task Name
        task_type:
          type: string
          title: Task Type
        executions:
          type: integer
          title: Executions
        completed:
          type: integer
          title: Completed
        failed:
          type: integer
          title: Failed
        bytes_transferred:
          type: integer
          title: Bytes Transferred
        files_transferred:
          type: integer
          title: Files Transferred
        avg_duration_seconds:
          anyOf:
            - type: number
            - type: 'null'
          title: Avg Duration Seconds
      type: object
      required:
        - task_id
        - task_name
        - task_type
        - executions
        - completed
        - failed
        - bytes_transferred
        - files_transferred
        - avg_duration_seconds
      title: TaskBreakdown
      description: Per-task aggregate stats.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````