Create Analysis

Submits a call recording for transcription and AI-powered analysis.

Endpoint

POST /api/v1/analysis/

Authentication

Requires API key (recommended) or JWT token.

Method	Header	Example
API Key	X-API-Key: {api_key}	X-API-Key: sk_live_abc123...
JWT Token	Authorization: Bearer {token}	Authorization: Bearer eyJhbGc...

Request

Content-Type

Required: multipart/form-data

This endpoint accepts file uploads only (not JSON). Use form-data to submit the audio file.

Form Data Parameters

Parameter	Type	Required	Description
agent_id	string	Yes	Internal identifier for the agent on the call
contact_id	string	Yes	Internal identifier for the customer/contact
audio_file	file	Yes	Audio file to analyze (multipart upload)
webhook_url	string	No	URL to receive notification when analysis completes

Supported Audio Formats

Supported formats:

• flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm

Limits:

• Maximum file size: 500 MB
• Files are securely stored and processed in the cloud

Response

Returns an AnalysisResponse object with status: "processing".

The analysis runs asynchronously in the background. Use webhooks (recommended) or polling to get results when complete.

Success Response (201 Created)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "analysis",
  "created": 1705334400,
  "status": "processing",
  "livemode": false,
  "call": {
    "agent_id": "agent_001",
    "contact_id": "customer_12345",
    "duration_ms": 125500,
    "duration_seconds": 125.5
  },
  "audio": {
    "url": "https://s3.amazonaws.com/callcov-audio/...",
    "size_bytes": 1048576,
    "format": "wav",
    "duration_seconds": 125.5
  },
  "transcript": null,
  "results": null,
  "metadata": {
    "webhook_url": "https://your-app.com/webhooks/analysis",
    "completed_at": null,
    "processing_time_ms": null,
    "error_message": null
  }
}

Response Fields

Field	Type	Description
id	UUID	Unique analysis identifier
object	string	Always "analysis"
created	integer	Unix timestamp of creation
status	string	"processing", "completed", or "failed"
livemode	boolean	Always false (test mode not implemented)
call.agent_id	string	Your agent identifier
call.contact_id	string	Your contact identifier
call.duration_ms	integer	Audio duration in milliseconds
audio.url	string	S3 URL where audio is stored
audio.size_bytes	integer	File size in bytes
audio.format	string	Audio format (wav, mp3, etc.)
transcript	object	null until processing completes
results	object	null until processing completes
metadata.webhook_url	string	Your webhook URL (if provided)

Examples

curl -X POST https://api.callcov.com/api/v1/analysis/ \
-H "X-API-Key: sk_live_abc123..." \
-F "audio_file=@/path/to/call-recording.wav" \
-F "agent_id=agent_001" \
-F "contact_id=customer_12345" \
-F "webhook_url=https://your-app.com/webhooks/analysis"

Errors

400 Bad Request

Unsupported audio format:

{
  "detail": "Unsupported audio file format. Supported formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm"
}

401 Unauthorized

Invalid or missing API key:

{
  "detail": "Invalid authentication credentials"
}

402 Payment Required

Billing limit exceeded:

{
  "detail": "Usage limit exceeded. Current usage: 150.5 minutes. Plan limit: 100 minutes."
}

Or overage cap reached:

{
  "detail": "Overage limit of 50 minutes exceeded. Please upgrade your plan or wait for the next billing cycle."
}

500 Internal Server Error

S3 upload failed:

{
  "detail": "Failed to upload audio file"
}

Unexpected error:

{
  "detail": "An unexpected error occurred"
}

How It Works

1. Upload: Audio file is uploaded securely to cloud storage
2. Queue: Analysis task is queued for processing
3. Transcribe: AI transcribes audio with speaker diarization
4. Analyze: Advanced AI analyzes transcript for compliance, quality, and coaching insights
5. Notify: Webhook is sent (if provided) when complete
6. Bill: Minutes are tracked and billed to your subscription

Processing Time

Typical processing times:

• Short calls (< 5 min): 30-90 seconds
• Medium calls (5-15 min): 1-3 minutes
• Long calls (15-60 min): 3-8 minutes

Use Webhooks

Use webhooks instead of polling. You'll be notified immediately when analysis completes.

Billing

• Charged by duration: Audio duration rounded up to nearest 0.01 minute
• Plans: Free (100 min/month), Starter ($49/month, 1000 min), Growth ($199/month, 5000 min)
• Overage: Charged per minute over plan limit (if overage cap allows)
• Billing check: API validates usage limits before accepting analysis

See Billing Guide for complete pricing details.

Related

• Get Analysis - Retrieve analysis by ID
• List Analyses - List all analyses with filters
• Webhooks Guide - Real-time notifications