List Analyses

Retrieves a list of all analyses for your account. Supports filtering, search, and pagination.

Endpoint

GET /api/v1/analysis/

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

Listing analyses is free - it does not count against your usage limits.

Query Parameters

Parameter	Type	Required	Default	Description
status_filter	string	No	-	Filter by status: processing, completed, or failed
agent_id	string	No	-	Filter by specific agent ID
contact_id	string	No	-	Filter by specific contact ID
search	string	No	-	Search in agent_id and contact_id (case-insensitive)
limit	integer	No	100	Maximum number of results to return (1-1000)
offset	integer	No	0	Number of results to skip (for pagination)

Filter Examples

# Get only completed analyses
?status_filter=completed

# Get all analyses for a specific agent
?agent_id=agent_001

# Get all analyses for a specific contact
?contact_id=customer_12345

# Search for analyses containing "agent_001"
?search=agent_001

# Combine filters
?status_filter=completed&agent_id=agent_001&limit=50

Response

Returns an AnalysisList object containing an array of analyses and pagination metadata.

Success Response (200 OK)

{
  "object": "list",
  "data": [
    {
      "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": "Full transcript...",
        "segments": [...],
        "language": "en"
      },
      "results": {
        "compliance": {
          "identity_verification": {...},
          "mandatory_disclosures": {...},
          "purpose_declaration": {...}
        },
        "quality": {
          "sentiment_analysis": {...},
          "greeting": {...},
          "empathetic_language": {...}
        },
        "coaching": {
          "recommendations": [...],
          "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
      }
    },
    {
      "id": "660f9511-f3ac-52e5-b827-557766551111",
      "object": "analysis",
      "created": 1705330800,
      "status": "processing",
      "livemode": false,
      "call": {
        "agent_id": "agent_002",
        "contact_id": "customer_67890",
        "duration_ms": 98200,
        "duration_seconds": 98.2
      },
      "audio": {
        "url": "https://s3.amazonaws.com/callcov-audio/...",
        "size_bytes": 823456,
        "format": "mp3",
        "duration_seconds": 98.2
      },
      "transcript": null,
      "results": null,
      "metadata": {
        "webhook_url": null,
        "completed_at": null,
        "processing_time_ms": null,
        "error_message": null
      }
    }
  ],
  "has_more": true,
  "total": 247
}

Response Fields

Field	Type	Description
object	string	Always "list"
data	array	Array of AnalysisResponse objects
has_more	boolean	Whether there are more results available
total	integer	Total number of analyses matching the filters

Pagination

Results are returned in reverse chronological order (newest first) by creation date.

Basic Pagination

import requests

url = "https://api.callcov.com/api/v1/analysis/"
headers = {"X-API-Key": "sk_live_abc123..."}

# Get first page (analyses 0-99)
response = requests.get(url, headers=headers, params={
    "limit": 100,
    "offset": 0
})

# Get second page (analyses 100-199)
response = requests.get(url, headers=headers, params={
    "limit": 100,
    "offset": 100
})

Iterate Through All Pages

import requests

def get_all_analyses(api_key, status_filter=None):
    """
    Fetch all analyses across all pages.

    Args:
        api_key: Your API key
        status_filter: Optional status filter

    Returns:
        List of all analyses
    """
    url = "https://api.callcov.com/api/v1/analysis/"
    headers = {"X-API-Key": api_key}

    all_analyses = []
    offset = 0
    limit = 100

    while True:
        params = {"limit": limit, "offset": offset}
        if status_filter:
            params["status_filter"] = status_filter

        response = requests.get(url, headers=headers, params=params)
        data = response.json()

        all_analyses.extend(data['data'])

        if not data['has_more']:
            break

        offset += limit

    return all_analyses

# Usage
completed_analyses = get_all_analyses(
    api_key="sk_live_abc123...",
    status_filter="completed"
)
print(f"Total completed analyses: {len(completed_analyses)}")

Examples

# Get all analyses
curl "https://api.callcov.com/api/v1/analysis/" \
-H "X-API-Key: sk_live_abc123..."

# Get only completed analyses
curl "https://api.callcov.com/api/v1/analysis/?status_filter=completed" \
-H "X-API-Key: sk_live_abc123..."

# Filter by agent
curl "https://api.callcov.com/api/v1/analysis/?agent_id=agent_001" \
-H "X-API-Key: sk_live_abc123..."

# Search with pagination
curl "https://api.callcov.com/api/v1/analysis/?search=customer&limit=50&offset=0" \
-H "X-API-Key: sk_live_abc123..."

Filtering Examples

Get Recent Completed Analyses

import requests

url = "https://api.callcov.com/api/v1/analysis/"
headers = {"X-API-Key": "sk_live_abc123..."}

response = requests.get(url, headers=headers, params={
    "status_filter": "completed",
    "limit": 10  # Last 10 completed
})

analyses = response.json()['data']
for analysis in analyses:
    effort_score = analysis['results']['coaching']['customer_effort_score']
    greeting_ok = analysis['results']['quality']['greeting']['present']
    print(f"{analysis['call']['contact_id']}: CES={effort_score}/5, Greeting={greeting_ok}")

Get All Analyses for Agent

def get_agent_analyses(api_key, agent_id):
    """Get all analyses for a specific agent"""
    url = "https://api.callcov.com/api/v1/analysis/"
    headers = {"X-API-Key": api_key}

    response = requests.get(url, headers=headers, params={
        "agent_id": agent_id,
        "limit": 1000  # Adjust as needed
    })

    data = response.json()
    return data['data'], data['total']

analyses, total = get_agent_analyses("sk_live_abc123...", "agent_001")
print(f"Agent agent_001 has {total} total analyses")

Search Across Analyses

# Search for analyses containing "customer_123"
response = requests.get(url, headers=headers, params={
    "search": "customer_123"
})

# This searches in both agent_id AND contact_id fields

Get Failed Analyses for Debugging

response = requests.get(url, headers=headers, params={
    "status_filter": "failed",
    "limit": 50
})

failed_analyses = response.json()['data']
for analysis in failed_analyses:
    error = analysis['metadata']['error_message']
    print(f"Analysis {analysis['id']} failed: {error}")

Performance Tips

1. Use Filters: Filter by status or agent_id to reduce result set size
2. Limit Results: Request only the number of results you need
3. Cache Results: Cache list results to avoid repeated API calls
4. Use Webhooks: Instead of polling the list endpoint for new completions, use webhooks

Errors

401 Unauthorized

Invalid or missing authentication:

{
  "detail": "Invalid authentication credentials"
}

422 Validation Error

Invalid parameter values:

{
  "detail": [
    {
      "loc": ["query", "limit"],
      "msg": "ensure this value is less than or equal to 1000",
      "type": "value_error.number.not_le"
    }
  ]
}

Common Use Cases

Dashboard: Show Recent Activity

# Get last 20 analyses for dashboard
response = requests.get(url, headers=headers, params={"limit": 20})
recent = response.json()['data']

Analytics: Calculate Average Quality Score

# Get all completed analyses
all_analyses = get_all_analyses(
    api_key="sk_live_abc123...",
    status_filter="completed"
)

# Calculate average customer effort score
total_effort = sum(
    a['results']['coaching']['customer_effort_score']
    for a in all_analyses
    if a['results']
)
avg_effort = total_effort / len(all_analyses)
print(f"Average customer effort score: {avg_effort:.2f}/5")

Agent Performance Report

# Get all completed analyses for specific agent
response = requests.get(url, headers=headers, params={
    "agent_id": "agent_001",
    "status_filter": "completed"
})

agent_analyses = response.json()['data']

# Calculate metrics
total_calls = len(agent_analyses)
avg_effort = sum(a['results']['coaching']['customer_effort_score'] for a in agent_analyses) / total_calls
compliance_rate = sum(1 for a in agent_analyses
                      if not a['results']['compliance']['identity_verification']['flagged']) / total_calls

print(f"Agent agent_001 Report:")
print(f"  Total calls: {total_calls}")
print(f"  Avg customer effort: {avg_effort:.2f}/5")
print(f"  Compliance rate: {compliance_rate:.1%}")

Security

• User Isolation: You can only list analyses that belong to your account
• API Key Scoping: API keys are scoped to your user account
• No Cross-Account Access: Cannot see other users' analyses

Related

• Create Analysis - Submit audio for analysis
• Retrieve Analysis - Get specific analysis by ID
• API Overview - General pagination info