Retrieve Analysis

Retrieves a specific analysis by its unique ID. Use this endpoint to check the status and get results of an analysis.

Endpoint

GET /api/v1/analysis/{analysis_id}

Authentication

Requires API key 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...`

Free Endpoint

Retrieving analyses is free - it does not count against your usage limits. Only creating new analyses consumes minutes.

Path Parameters

Parameter	Type	Required	Description
`analysis_id`	UUID	Yes	Unique analysis identifier returned when analysis was created

Response

Returns the full AnalysisResponse object with current status and results (if completed).

Success Response (200 OK)

When analysis is still processing:

{
  "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
  }
}

When analysis is completed:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "analysis",
  "created": 1705334400,
  "status": "completed",
  "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": {
    "text": "Agent: Hello, thank you for calling. How can I help you today?\nCustomer: Hi, I'm having issues with my account...",
    "segments": [
      {
        "speaker": "A",
        "text": "Hello, thank you for calling. How can I help you today?",
        "start": 0.0,
        "end": 3.2
      },
      {
        "speaker": "B",
        "text": "Hi, I'm having issues with my account.",
        "start": 3.5,
        "end": 5.8
      }
    ],
    "language": "en"
  },
  "results": {
    "compliance": {
      "identity_verification": {
        "verified": true,
        "timestamp": 0.0,
        "flagged": false
      },
      "mandatory_disclosures": {
        "read": true,
        "matched_disclosures": ["call_recording_notice"],
        "missing_disclosures": []
      },
      "purpose_declaration": {
        "disclosed": true,
        "interaction_number": 1,
        "flagged": false
      },
      "prohibited_phrases": {
        "used": false,
        "instances": []
      },
      "sensitive_data": {
        "shared": false,
        "instances": []
      }
    },
    "quality": {
      "sentiment_analysis": {
        "trajectory": [
          {"timestamp": 0.0, "level": 4},
          {"timestamp": 30.0, "level": 5}
        ],
        "first_30s_avg": 4,
        "last_30s_avg": 5,
        "drop_magnitude": 0,
        "flagged_drop": false,
        "negative_periods": []
      },
      "greeting": {
        "present": true,
        "timestamp": 0.0,
        "flagged_missing": false,
        "flagged_late": false
      },
      "call_structure": {
        "follows_structure": true,
        "stages_completed": ["Greeting", "Purpose", "Discussion", "Resolution", "Close"],
        "missing_stages": []
      },
      "resolution_marker": {
        "confirmed": true,
        "timestamp": 20.0
      },
      "empathetic_language": {
        "used": true,
        "instances": [6.0, 12.3],
        "three_min_intervals_checked": 1,
        "intervals_without_empathy": 0,
        "flagged": false
      },
      "objections": {
        "identified": [],
        "flagged_unhandled": false,
        "initial_purpose_addressed": true
      },
      "persuasion_markers": {
        "count": 0,
        "instances": []
      },
      "interruptions": {
        "count": 0,
        "instances": [],
        "flagged": false
      },
      "language_adequacy": {
        "appropriate": true,
        "issues": [],
        "flagged": false
      }
    },
    "coaching": {
      "recommendations": [
        {
          "category": "greeting",
          "priority": "low",
          "description": "Agent provided an excellent greeting and immediately offered assistance"
        },
        {
          "category": "empathy",
          "priority": "medium",
          "description": "Consider using more empathetic language when acknowledging customer issues"
        }
      ],
      "customer_effort_score": 1
    }
  },
  "metadata": {
    "webhook_url": "https://your-app.com/webhooks/analysis",
    "completed_at": "2024-01-15T14:32:15.123Z",
    "processing_time_ms": 45230,
    "error_message": null
  }
}

Response Fields

Complete Field Reference

For a comprehensive, auto-generated field reference with all nested fields, see the Analysis Fields Reference.

Top-Level Fields:

Field	Type	Description
`id`	UUID	Unique analysis identifier
`object`	string	Always "analysis"
`created`	integer	Unix timestamp of creation
`status`	string	Current status: "processing", "completed", or "failed"
`livemode`	boolean	Always false (test mode not implemented)
`call`	object	Call-related information (agent_id, contact_id, duration)
`audio`	object	Audio file information (url, size, format, duration)
`transcript`	object	Transcript information (null until complete)
`results`	object	Comprehensive analysis results (null until complete)
`metadata`	object	Metadata and processing information

Call Fields:

Field	Type	Description
`call.agent_id`	string	Your agent identifier
`call.contact_id`	string	Your contact identifier
`call.duration_ms`	integer	Audio duration in milliseconds
`call.duration_seconds`	float	Audio duration in seconds (computed)

Audio Fields:

Field	Type	Description
`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.)
`audio.duration_seconds`	float	Audio duration in seconds

Transcript Fields:

Field	Type	Description
`transcript.text`	string	Full transcript text
`transcript.segments`	array	Transcript segments with speaker diarization and timestamps
`transcript.language`	string	Detected language code (e.g., "en", "es")

Results Structure:

Field	Type	Description
`results.compliance`	object	Compliance checks - see Compliance Fields
`results.quality`	object	Quality metrics - see Quality Fields
`results.coaching`	object	Coaching recommendations - see Coaching Fields

Metadata Fields:

Field	Type	Description
`metadata.webhook_url`	string	Your webhook URL (if provided)
`metadata.completed_at`	datetime	Completion timestamp (null until complete)
`metadata.processing_time_ms`	integer	Total processing time in ms
`metadata.error_message`	string	Error message if status is "failed"

Status Values

Status	Description
`processing`	Analysis is currently being processed
`completed`	Analysis completed successfully, results available
`failed`	Analysis failed, check `error_message` for details

Examples

# Using API Key
curl https://api.callcov.com/api/v1/analysis/550e8400-e29b-41d4-a716-446655440000 \
-H "X-API-Key: sk_live_abc123..."

# Using JWT Token
curl https://api.callcov.com/api/v1/analysis/550e8400-e29b-41d4-a716-446655440000 \
-H "Authorization: Bearer eyJhbGc..."

Polling for Results

If you didn't provide a webhook URL during creation, you'll need to poll this endpoint to check when analysis completes.

Polling Pattern

import requests
import time

def wait_for_analysis(analysis_id, api_key, timeout=300, interval=5):
    """
    Poll for analysis completion.

    Args:
        analysis_id: UUID of the analysis
        api_key: Your API key
        timeout: Maximum time to wait (seconds)
        interval: Time between polls (seconds)

    Returns:
        Completed analysis object or None if timeout
    """
    url = f"https://api.callcov.com/api/v1/analysis/{analysis_id}"
    headers = {"X-API-Key": api_key}

    elapsed = 0
    while elapsed < timeout:
        response = requests.get(url, headers=headers)

        if response.status_code == 200:
            analysis = response.json()

            if analysis['status'] == 'completed':
                return analysis
            elif analysis['status'] == 'failed':
                raise Exception(f"Analysis failed: {analysis['metadata']['error_message']}")

        time.sleep(interval)
        elapsed += interval

    return None  # Timeout

# Usage
analysis = wait_for_analysis(
    analysis_id="550e8400-e29b-41d4-a716-446655440000",
    api_key="sk_live_abc123...",
    timeout=300,
    interval=5
)

if analysis:
    print("Analysis complete!")
    print(analysis['results'])
else:
    print("Timeout waiting for analysis")

Use Webhooks Instead

Polling is inefficient and can hit rate limits. Use webhooks for production applications to get notified immediately when analysis completes.

Errors

401 Unauthorized

Invalid or missing authentication:

{
  "detail": "Invalid authentication credentials"
}

404 Not Found

Analysis doesn't exist or doesn't belong to your account:

{
  "detail": "Analysis not found"
}

Security

User Isolation: You can only retrieve analyses that belong to your account
API Key Scoping: API keys are scoped to your user account
JWT Validation: JWT tokens are validated for expiration and signature

Create Analysis - Submit audio for analysis
List Analyses - List all your analyses
Webhooks Guide - Get notified when complete
Analysis Fields Reference - Complete field documentation
API Response Examples - Real-world response examples

Endpoint​

Authentication​

Path Parameters​

Response​

Success Response (200 OK)​

Response Fields​

Status Values​

Examples​

Polling for Results​

Polling Pattern​

Errors​

401 Unauthorized​

404 Not Found​

Security​

Related​