Private Beta—ProposeFlow is currently in private beta.Join the waitlist
ProposeFlow

Analytics

Track user engagement, schema performance, and generation patterns with the ProposeFlow Analytics API.

Overview

The Analytics API provides insights into how users interact with your ProposeFlow integration. Monitor active users, track acceptance rates, and identify popular generation inputs to optimize your AI-assisted workflows.

User Engagement

Track daily, weekly, and monthly active users based on proposal generation activity.

Schema Performance

Measure acceptance rates and iteration counts to understand how well your schemas guide AI generation.

Popular Inputs

Discover what users are generating most frequently to optimize prompts and schemas.

Credit Usage

Monitor credit consumption by schema and model tier to optimize costs.

GET /v1/analytics

Retrieve aggregated analytics across all users and schemas for your application.

Request
curl -X GET https://api.proposeflow.com/v1/analytics \
  -H "Authorization: Bearer pf_your_api_key"

Response

Response
{
  "users": {
    "total": 150,
    "monthlyActive": 89,
    "weeklyActive": 45,
    "dailyActive": 12
  },
  "schemas": [
    {
      "id": "sch_abc123",
      "name": "blogPost",
      "version": "1.0.0",
      "proposalsGenerated": 1250,
      "acceptanceRate": 78.5,
      "medianIterations": 1.5,
      "proposalsLast30Days": 320
    },
    {
      "id": "sch_def456",
      "name": "recipe",
      "version": "1.0.0",
      "proposalsGenerated": 890,
      "acceptanceRate": 85.2,
      "medianIterations": 1.2,
      "proposalsLast30Days": 215
    }
  ],
  "period": {
    "start": "2024-12-19T00:00:00.000Z",
    "end": "2025-01-18T00:00:00.000Z"
  }
}

Response Fields

users

totalTotal registered users (tenants)
monthlyActiveUsers with proposals in last 30 days
weeklyActiveUsers with proposals in last 7 days
dailyActiveUsers with proposals in last 24 hours

schemas[]

proposalsGeneratedTotal proposals created for this schema
acceptanceRatePercentage of proposals approved (0-100)
medianIterationsMedian regeneration cycles before approval
proposalsLast30DaysProposals generated in the last 30 days

GET /v1/analytics/schemas/:schemaId

Get detailed analytics for a specific schema, including popular generation inputs.

Query Parameters

periodoptional
"day" | "week" | "month" (default: "month")
limitoptional
Number of popular inputs to return (1-100, default: 10)
Request
curl -X GET "https://api.proposeflow.com/v1/analytics/schemas/sch_abc123?period=week&limit=5" \
  -H "Authorization: Bearer pf_your_api_key"

Response

Response
{
  "schema": {
    "id": "sch_abc123",
    "name": "blogPost",
    "version": "1.0.0",
    "description": "Blog post content schema"
  },
  "metrics": {
    "proposalsGenerated": 85,
    "acceptanceRate": 82.4,
    "medianIterations": 1.3,
    "approvedCount": 70,
    "rejectedCount": 8,
    "pendingCount": 7
  },
  "popularInputs": [
    {
      "input": "Write a blog post about TypeScript best practices",
      "count": 12,
      "approvedCount": 10,
      "rejectedCount": 1,
      "lastUsedAt": "2025-01-18T14:30:00.000Z"
    },
    {
      "input": "Create a tutorial on React hooks",
      "count": 8,
      "approvedCount": 7,
      "rejectedCount": 0,
      "lastUsedAt": "2025-01-17T09:15:00.000Z"
    }
  ],
  "period": {
    "start": "2025-01-11T00:00:00.000Z",
    "end": "2025-01-18T00:00:00.000Z"
  }
}

Tracking User Activity

To track individual user activity in analytics, pass a subject when generating proposals. The userId or tenantId field is used to calculate active user metrics.

track-user.ts
const { proposal } = await pf.generate('blogPost', {
  input: 'Write a post about AI safety',
  subject: {
    userId: 'user_123',      // Used for active user metrics
    tenantId: 'tenant_456',  // Fallback if userId not provided
    // Add any other context you want to track
    plan: 'enterprise',
    team: 'engineering',
  },
});

Privacy note: Subject data is stored with proposals for analytics purposes. Avoid including sensitive personal information in the subject field.

Understanding Metrics

Acceptance Rate

The percentage of proposals that users approved. A higher rate indicates your schemas and prompts are generating content that meets user expectations. If the rate is low, consider improving your schema descriptions or adjusting AI parameters.

Median Iterations

The median number of generation attempts before a proposal is approved. A value of 1.0 means most proposals are approved on the first try. Higher values indicate users frequently request regeneration with feedback, which may signal areas for improvement.

Popular Inputs

The most frequently used generation prompts, along with their approval rates. Use this data to identify common use cases and optimize your schemas for popular requests.

Credit Usage Tracking

Monitor credit consumption across your application with the usage API. Track spending by model tier and schema to optimize costs.

GET /v1/usage

Request
curl -X GET https://api.proposeflow.com/v1/usage \
  -H "Authorization: Bearer pf_your_api_key"

Response

Response
{
  "credits": {
    "used": 1250.5,
    "limit": 10000,
    "remaining": 8749.5
  },
  "byTier": {
    "fast": 50.2,
    "balanced": 800.3,
    "quality": 400.0
  },
  "bySchema": [
    {
      "schemaId": "sch_abc123",
      "schemaName": "blogPost",
      "credits": 650.5,
      "generations": 145
    },
    {
      "schemaId": "sch_def456",
      "schemaName": "recipe",
      "credits": 420.0,
      "generations": 280
    }
  ],
  "period": {
    "start": "2025-01-01T00:00:00.000Z",
    "end": "2025-02-01T00:00:00.000Z"
  }
}

Response Fields

credits.usedTotal credits consumed this period
credits.limitCredit limit for current billing period
byTierBreakdown by model tier (fast, balanced, quality)
bySchemaPer-schema credit consumption and generation count

See Model Tiers & Credits for details on credit calculation and cost optimization strategies.

CLI: proposeflow analytics

View analytics directly from your terminal using the ProposeFlow CLI. The command displays formatted statistics with progress bars and sparklines.

Terminal
# View overall analytics
proposeflow analytics

# View analytics for a specific schema
proposeflow analytics --schema recipe

# Filter by time period (day, week, or month)
proposeflow analytics --schema recipe --period week

Example Output

Output
Period: Dec 19 - Jan 18

Users
────────────────────────────────────
  Total registered     125
  Monthly active       89
  Weekly active        45
  Daily active         12

Schemas
────────────────────────────────────
  Total proposals:   1,234
  Last 30 days:      456
  Avg acceptance:    78.5%

  Per schema:

  recipe@1.0.0
    Proposals: 890  Acceptance: ████████░░ 82.3%  Iterations: 1.4

The CLI is also available in the interactive TUI under Usage → Analytics.

Authentication

The Analytics API requires authentication using your API key. All analytics are scoped to your application, ensuring complete data isolation between tenants.

Authentication
# Using API key
curl -X GET https://api.proposeflow.com/v1/analytics \
  -H "Authorization: Bearer pf_your_api_key"

# Using dashboard authentication (internal)
curl -X GET https://api.proposeflow.com/v1/analytics \
  -H "Authorization: Bearer <clerk_jwt>" \
  -H "X-Application-Id: app_your_id"