Reports API

The Reports API provides functionality for creating, configuring, and running analytics reports. Supports on-demand execution, scheduled delivery, and multiple output formats.

Report Configuration Object

{
  id: string;                    // UUID
  organization_id: string;       // UUID of the organization
  created_by: string;            // UUID of the creator
  name: string;                  // Report name
  description?: string;          // Report description
  type: ReportType;              // Report type
  config: {
    filters: ReportFilter[];     // Data filters
    grouping: ReportGrouping[];  // Data grouping
    metrics: ReportMetric[];     // Metrics to calculate
    dateRange: DateRange;        // Time period
  };
  created_at: string;            // ISO timestamp
  updated_at: string;            // ISO timestamp
}

Report Types

Filter Schema

{
  field: string;                 // Field to filter on
  operator: 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'in';
  value: string | number | string[];
}

Grouping Schema

{
  field: string;                 // Field to group by
  interval?: 'day' | 'week' | 'month' | 'quarter' | 'year';  // For date fields
}

Metric Schema

{
  field: string;                 // Field to aggregate
  aggregation: 'count' | 'sum' | 'avg' | 'min' | 'max';
  label?: string;                // Display label
}

Date Range

{
  type: 'relative' | 'absolute';
  value: string;                 // "30d", "7d", "90d" or "2024-01-01,2024-01-31"
}

List Reports

List all saved report configurations.

Procedure: reports.list

Authentication: Required

Input: None

Example:

curl -X GET "https://your-domain.com/api/trpc/reports.list" \
  -H "Cookie: your-session-cookie"

Response:

{
  "result": {
    "data": {
      "json": [
        {
          "id": "uuid",
          "name": "Monthly Ticket Summary",
          "description": "Overview of ticket metrics for the month",
          "type": "ticket_summary",
          "config": {
            "filters": [],
            "grouping": [{ "field": "status" }],
            "metrics": [{ "field": "id", "aggregation": "count", "label": "Total Tickets" }],
            "dateRange": { "type": "relative", "value": "30d" }
          },
          "created_at": "2024-01-01T00:00:00.000Z",
          "updated_at": "2024-01-15T10:00:00.000Z"
        }
      ]
    }
  }
}

Get Report by ID

Retrieve a specific report configuration.

Procedure: reports.getById

Authentication: Required

Input:

{
  id: string;  // Report UUID
}

Example:

curl -X GET "https://your-domain.com/api/trpc/reports.getById?input=%7B%22id%22:%22report-uuid%22%7D" \
  -H "Cookie: your-session-cookie"

Response:

{
  "result": {
    "data": {
      "json": {
        "id": "uuid",
        "name": "Monthly Ticket Summary",
        "type": "ticket_summary",
        "config": {
          "filters": [],
          "grouping": [{ "field": "status" }],
          "metrics": [{ "field": "id", "aggregation": "count" }],
          "dateRange": { "type": "relative", "value": "30d" }
        }
      }
    }
  }
}

Create Report

Create a new report configuration.

Procedure: reports.create

Authentication: Required

Input:

{
  name: string;                  // 1-100 characters
  description?: string;          // Max 500 characters
  type: ReportType;              // Report type
  filters?: ReportFilter[];      // Default: []
  grouping?: ReportGrouping[];   // Default: []
  metrics?: ReportMetric[];      // Default: []
  dateRange: DateRange;          // Required
}

Example:

curl -X POST "https://your-domain.com/api/trpc/reports.create" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "json": {
      "name": "Weekly Agent Performance",
      "description": "Agent metrics for the past week",
      "type": "agent_performance",
      "grouping": [{ "field": "assignee_id" }],
      "metrics": [
        { "field": "id", "aggregation": "count", "label": "Tickets Handled" },
        { "field": "resolution_rate", "aggregation": "avg", "label": "Resolution %" }
      ],
      "dateRange": { "type": "relative", "value": "7d" }
    }
  }'

Response:

{
  "result": {
    "data": {
      "json": {
        "id": "new-uuid",
        "name": "Weekly Agent Performance",
        "type": "agent_performance",
        "created_at": "2024-01-15T10:30:00.000Z"
      }
    }
  }
}

Update Report

Update an existing report configuration.

Procedure: reports.update

Authentication: Required

Input:

{
  id: string;                    // Report UUID (required)
  name?: string;
  description?: string;
  filters?: ReportFilter[];
  grouping?: ReportGrouping[];
  metrics?: ReportMetric[];
  dateRange?: DateRange;
}

Example:

curl -X POST "https://your-domain.com/api/trpc/reports.update" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "json": {
      "id": "report-uuid",
      "name": "Monthly Agent Performance",
      "dateRange": { "type": "relative", "value": "30d" }
    }
  }'

Delete Report

Delete a report configuration.

Procedure: reports.delete

Authentication: Required

Input:

{
  id: string;  // Report UUID
}

Example:

curl -X POST "https://your-domain.com/api/trpc/reports.delete" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{"json":{"id":"report-uuid"}}'

Response:

{
  "result": {
    "data": {
      "json": {
        "success": true
      }
    }
  }
}

Run Report

Execute a report and get results. Admin only.

Procedure: reports.run

Authentication: Required (Admin)

Input:

{
  // Option 1: Use saved report config
  id?: string;                   // Report UUID

  // Option 2: Provide inline config
  type?: ReportType;
  filters?: ReportFilter[];
  grouping?: ReportGrouping[];
  metrics?: ReportMetric[];
  dateRange?: DateRange;

  // Output format
  format?: 'pdf' | 'csv' | 'json';  // Default: 'json'
}

Example (using saved config):

curl -X POST "https://your-domain.com/api/trpc/reports.run" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "json": {
      "id": "report-uuid",
      "format": "json"
    }
  }'

Example (inline config):

curl -X POST "https://your-domain.com/api/trpc/reports.run" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "json": {
      "type": "ticket_summary",
      "dateRange": { "type": "relative", "value": "7d" },
      "format": "json"
    }
  }'

Response (Ticket Summary):

{
  "result": {
    "data": {
      "json": {
        "data": [
          { "category": "Summary", "metric": "Total Tickets", "value": 150 },
          { "category": "By Status", "metric": "open", "value": 45 },
          { "category": "By Status", "metric": "resolved", "value": 80 },
          { "category": "By Priority", "metric": "high", "value": 25 },
          { "category": "By Priority", "metric": "normal", "value": 100 }
        ],
        "count": 5,
        "executedAt": "2024-01-15T10:30:00.000Z",
        "format": "json"
      }
    }
  }
}

Response (Agent Performance):

{
  "result": {
    "data": {
      "json": {
        "data": [
          {
            "agent_name": "John Smith",
            "agent_email": "john@example.com",
            "total_tickets": 45,
            "resolved_tickets": 38,
            "resolution_rate": 84
          },
          {
            "agent_name": "Jane Doe",
            "agent_email": "jane@example.com",
            "total_tickets": 52,
            "resolved_tickets": 48,
            "resolution_rate": 92
          }
        ],
        "count": 2,
        "executedAt": "2024-01-15T10:30:00.000Z",
        "format": "json"
      }
    }
  }
}

Schedule Report

Schedule a report for recurring email delivery. Admin only.

Procedure: reports.schedule

Authentication: Required (Admin)

Input:

{
  reportId: string;              // Report UUID
  frequency: 'daily' | 'weekly' | 'monthly';
  recipients: string[];          // Email addresses (min 1)
  format?: 'pdf' | 'csv' | 'json';  // Default: 'pdf'
  enabled?: boolean;             // Default: true
}

Example:

curl -X POST "https://your-domain.com/api/trpc/reports.schedule" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "json": {
      "reportId": "report-uuid",
      "frequency": "weekly",
      "recipients": ["manager@example.com", "team@example.com"],
      "format": "pdf",
      "enabled": true
    }
  }'

Response:

{
  "result": {
    "data": {
      "json": {
        "id": "schedule-uuid",
        "report_config_id": "report-uuid",
        "frequency": "weekly",
        "recipients": ["manager@example.com", "team@example.com"],
        "format": "pdf",
        "enabled": true,
        "created_at": "2024-01-15T10:30:00.000Z"
      }
    }
  }
}

Get Report History

Get execution history for reports.

Procedure: reports.getHistory

Authentication: Required

Input:

{
  reportId?: string;   // Filter by specific report
  limit?: number;      // 1-100, default: 20
}

Example:

curl -X GET "https://your-domain.com/api/trpc/reports.getHistory?input=%7B%22limit%22:10%7D" \
  -H "Cookie: your-session-cookie"

Response:

{
  "result": {
    "data": {
      "json": [
        {
          "id": "execution-uuid",
          "report_type": "ticket_summary",
          "result_count": 25,
          "format": "json",
          "created_at": "2024-01-15T10:30:00.000Z",
          "executed_by": "user-uuid",
          "report_config": {
            "name": "Monthly Ticket Summary"
          }
        }
      ]
    }
  }
}

Get Report Templates

Get available report templates with default configurations.

Procedure: reports.getTemplates

Authentication: Required

Input: None

Example:

curl -X GET "https://your-domain.com/api/trpc/reports.getTemplates" \
  -H "Cookie: your-session-cookie"

Response:

{
  "result": {
    "data": {
      "json": [
        {
          "id": "ticket_summary",
          "name": "Ticket Summary Report",
          "description": "Overview of ticket volume, status distribution, and trends",
          "type": "ticket_summary",
          "defaultConfig": {
            "grouping": [{ "field": "status" }],
            "metrics": [{ "field": "id", "aggregation": "count", "label": "Total Tickets" }],
            "dateRange": { "type": "relative", "value": "30d" }
          }
        },
        {
          "id": "agent_performance",
          "name": "Agent Performance Report",
          "description": "Agent ticket handling, resolution rates, and response times",
          "type": "agent_performance",
          "defaultConfig": {
            "grouping": [{ "field": "assignee_id" }],
            "metrics": [
              { "field": "id", "aggregation": "count", "label": "Tickets Handled" },
              { "field": "resolution_rate", "aggregation": "avg", "label": "Resolution Rate" }
            ],
            "dateRange": { "type": "relative", "value": "30d" }
          }
        },
        {
          "id": "sla_compliance",
          "name": "SLA Compliance Report",
          "description": "Track SLA adherence for first response and resolution times",
          "type": "sla_compliance",
          "defaultConfig": {
            "grouping": [{ "field": "created_at", "interval": "week" }],
            "metrics": [
              { "field": "first_response_sla", "aggregation": "avg", "label": "First Response SLA %" },
              { "field": "resolution_sla", "aggregation": "avg", "label": "Resolution SLA %" }
            ],
            "dateRange": { "type": "relative", "value": "90d" }
          }
        },
        {
          "id": "volume_trends",
          "name": "Volume Trends Report",
          "description": "Ticket creation and resolution trends over time",
          "type": "volume_trends",
          "defaultConfig": {
            "grouping": [{ "field": "created_at", "interval": "day" }],
            "metrics": [{ "field": "id", "aggregation": "count", "label": "Tickets Created" }],
            "dateRange": { "type": "relative", "value": "30d" }
          }
        },
        {
          "id": "customer_activity",
          "name": "Customer Activity Report",
          "description": "Customer ticket submission patterns and satisfaction",
          "type": "customer_activity",
          "defaultConfig": {
            "grouping": [{ "field": "requester_id" }],
            "metrics": [
              { "field": "id", "aggregation": "count", "label": "Tickets Submitted" },
              { "field": "satisfaction_rating", "aggregation": "avg", "label": "Avg Satisfaction" }
            ],
            "dateRange": { "type": "relative", "value": "30d" }
          }
        }
      ]
    }
  }
}

Use Cases

Creating a Report from Template

// Get templates
const templates = await trpc.reports.getTemplates.query()
const template = templates.find(t => t.id === 'agent_performance')

// Create report from template
const report = await trpc.reports.create.mutate({
  name: 'Weekly Team Performance',
  description: 'Performance metrics for the support team',
  type: template.type,
  ...template.defaultConfig,
})

Running an Ad-Hoc Report

// Quick inline report without saving
const results = await trpc.reports.run.mutate({
  type: 'volume_trends',
  dateRange: { type: 'relative', value: '7d' },
  format: 'json',
})

// Display chart
renderChart(results.data)

Setting Up Weekly Email Reports

// Create report config
const report = await trpc.reports.create.mutate({
  name: 'Weekly Summary',
  type: 'ticket_summary',
  dateRange: { type: 'relative', value: '7d' },
})

// Schedule weekly delivery
await trpc.reports.schedule.mutate({
  reportId: report.id,
  frequency: 'weekly',
  recipients: ['team-lead@company.com'],
  format: 'pdf',
})

Error Codes