Skip to content

Usage & Billing

Vellocity uses a credit-based billing model for 3PI partners. Every API request that invokes an AI capability consumes credits based on the capability type and complexity.

Credit system

Credits are the unit of consumption for AI capabilities. Each capability has a defined credit cost:

Capability Category Credit Range Examples
AI GTM Engine 2–40 Campaign generation, workflow automation
Content Studio 10–30 Blog posts, email campaigns, SEO content
Co-Sell Intelligence 15–20 Partner matching, ICP analysis
Joint GTM Planner 40 Co-branded campaigns, content calendars
Marketplace Optimization 8–25 Listing SEO, launch readiness
Partner Central 10–15 ACE briefs, case studies
Media Studio 20 Images, videos, pitch decks
Analytics 10–15 Competitor analysis, deal influence
Knowledge Base RAG 2 Grounded conversations

Credit costs reflect the underlying AI compute required — more complex capabilities (multi-step agent workflows, image generation) consume more credits.

Usage tracking

Every API request is logged with detailed metadata:

Field Description
capability_slug Which capability was invoked
endpoint The API endpoint called
method HTTP method (GET, POST, etc.)
credits_consumed Credits charged for this request
input_tokens LLM input tokens used
output_tokens LLM output tokens generated
response_time_ms End-to-end response time
status success, error, or rate_limited
is_sandbox Whether this was a sandbox request
billing_date The billing date (UTC)

Querying usage

Daily summary

Get a breakdown of today's usage (or any specific date):

curl "https://api.vell.ai/api/v1/3pi-partners/42/usage?period=daily&date=2026-03-15" \
  -H "Authorization: Bearer $VELLOCITY_API_KEY"

{
  "data": {
    "date": "2026-03-15",
    "total_requests": 1247,
    "successful_requests": 1230,
    "failed_requests": 12,
    "rate_limited_requests": 5,
    "total_credits": 3850,
    "total_input_tokens": 524000,
    "total_output_tokens": 312000,
    "avg_response_time_ms": 1340,
    "by_capability": {
      "ai_writer": {"requests": 800, "credits": 2400},
      "marketplace_seo": {"requests": 300, "credits": 750},
      "cosell_matching": {"requests": 147, "credits": 700}
    }
  }
}

Monthly summary

Get aggregated usage for a billing period:

curl "https://api.vell.ai/api/v1/3pi-partners/42/usage?period=monthly&year=2026&month=3" \
  -H "Authorization: Bearer $VELLOCITY_API_KEY"

{
  "data": {
    "period": "2026-03",
    "total_requests": 18420,
    "total_credits": 52300,
    "total_input_tokens": 7240000,
    "total_output_tokens": 4180000,
    "unique_capabilities_used": 8,
    "daily_breakdown": [
      {"billing_date": "2026-03-01", "requests": 945, "credits": 2800},
      {"billing_date": "2026-03-02", "requests": 1102, "credits": 3100},
      {"billing_date": "2026-03-03", "requests": 1050, "credits": 2950}
    ]
  }
}

Daily credit limits

Set per-key daily credit limits to control spend:

curl -X POST https://api.vell.ai/api/v1/3pi-partners/42/keys \
  -H "Authorization: Bearer $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Budget-Limited Key",
    "daily_credit_limit": 5000
  }'

When a key hits its daily limit:

  • Subsequent requests return 429 with DAILY_CREDIT_LIMIT_EXCEEDED
  • The limit resets at midnight UTC
  • Sandbox requests are never limited

Sandbox billing

Mode Credits Usage Tracking
Sandbox Zero — no charges Tracked separately, excluded from billing
Production Charged per request Included in daily/monthly summaries

Sandbox mode is free regardless of volume. Use it liberally during development and integration testing.

Token tracking

Beyond credits, Vellocity tracks LLM token usage for transparency:

  • Input tokens: Tokens sent to the model (prompt, context, instructions)
  • Output tokens: Tokens generated by the model (response content)

Token counts are included in usage summaries and per-request logs. This helps you understand the computational cost behind each capability call.

Monitoring recommendations

  1. Poll daily usage — Check the daily summary endpoint at regular intervals to track consumption
  2. Set credit limits — Use daily_credit_limit on keys to prevent runaway costs
  3. Review capability breakdown — The by_capability field identifies which capabilities consume the most credits
  4. Watch error rates — A spike in failed_requests may indicate integration issues
  5. Track response times — avg_response_time_ms helps identify performance changes
  6. Compare periods — Use monthly summaries to track growth trends and forecast costs