> ## Documentation Index
> Fetch the complete documentation index at: https://docs.salesfinity.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve Scored Calls

> Retrieves a paginated list of AI-scored calls with detailed insights, scoring facets, lead qualification, and coaching recommendations.

Retrieves a paginated list of AI-scored calls. Each scored call includes detailed insights across six scoring facets (intro, discovery, pitch, tonality, objection handling, CTA), lead qualification data, coaching recommendations, and an overall score.

### Query Parameters

#### Pagination & Sorting

* **limit** (*optional*, number): Number of items per page (default: 10, max: 100)
* **page** (*optional*, number): The current page number to retrieve (default: 1)
* **sort** (*optional*, string): Sort field with optional `-` prefix for descending order (default: `-createdAt`)

#### Filters

* **start\_date** (*optional*, ISO 8601 date): Start of date range
* **end\_date** (*optional*, ISO 8601 date): End of date range
* **min\_score** (*optional*, number): Minimum total score (0-100)
* **max\_score** (*optional*, number): Maximum total score (0-100)
* **user\_id** (*optional*, string): Filter by user ID

### Example Requests

**Basic request:**

```
GET /v1/scored-calls?page=1&limit=10
```

**Filter by date range:**

```
GET /v1/scored-calls?start_date=2024-01-01&end_date=2024-01-31
```

**Filter by score range:**

```
GET /v1/scored-calls?min_score=70&max_score=100
```

**Filter by user and date:**

```
GET /v1/scored-calls?user_id=507f1f77bcf86cd799439033&start_date=2024-01-01&end_date=2024-01-31
```

### Response

Returns a JSON object containing the list of scored calls with pagination metadata.

```json theme={null}
{
  "data": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "insight": {
        "total_score": 78,
        "lead": {
          "function": "Sales",
          "tech_stack_mentioned": ["Salesforce", "Outreach"],
          "current_vendor": "Competitor Inc",
          "fit_score": 85,
          "is_decision_maker": true,
          "is_correct_persona": true,
          "pain_point_resonated": true,
          "is_qualified_meeting": true,
          "is_likely_to_buy": false,
          "prospect_lifecycle_stage": ["solution_aware"]
        },
        "messaging": {
          "value_prop_resonated": ["efficiency", "time_savings"],
          "objection_outcome": ["handled"],
          "emotional_triggers": ["frustration_with_current_tool"],
          "recommendation_to_nail_messaging": "Lead with ROI data specific to their industry"
        },
        "targeting_feedback": {
          "persona_fit": "excellent",
          "industry_fit": "good",
          "persona_seniority": "vp",
          "title_relevance": "good",
          "data_quality_issue": [],
          "future_follow_up_needed": true,
          "follow_up_reason": ["renewal"]
        },
        "metadata": {
          "duration_sec": 245,
          "asr_confidence_avg": 0.92,
          "audio_features_available": true,
          "talk_listen_ratio_rep": 0.45,
          "total_questions": 8,
          "open_question_ratio": 0.625,
          "interruptions_by_rep": 1,
          "core_pitch_duration_sec": 35,
          "estimated_wpm_rep": 155,
          "objections_detected": ["budget"]
        },
        "facets": {
          "intro": {
            "score": 85,
            "weight_pct": 10,
            "explanation": "Strong permission-based opener",
            "insufficient_evidence": false,
            "checks": {
              "permission_opener_used": true,
              "opener_length_sec": 12,
              "time_to_opener_sec": 3,
              "improvement_recommendation": "Consider a more personalized opener"
            }
          },
          "discovery": {
            "score": 72,
            "weight_pct": 25,
            "explanation": "Good question quality but missed timing topic",
            "insufficient_evidence": false,
            "metrics": {
              "total_questions": 8,
              "open_question_ratio": 0.625,
              "improvement_recommendation": "Ask about timeline and decision process",
              "topic_coverage": ["pain", "current_tools"]
            }
          },
          "pitch": {
            "score": 80,
            "weight_pct": 20,
            "explanation": "Well-tailored pitch to discovery findings",
            "insufficient_evidence": false,
            "metrics": {
              "core_pitch_duration_sec": 35,
              "tailored_to_discovery": true,
              "improvement_recommendation": "Include a customer success story",
              "outcome_keywords": ["efficiency", "save_time"]
            }
          },
          "tonality": {
            "score": 75,
            "weight_pct": 15,
            "explanation": "Good pace, minor filler word usage",
            "insufficient_evidence": false,
            "metrics": {
              "estimated_wpm": 155,
              "interruptions_by_rep": 1,
              "filler_density_per_min": 2.1,
              "improvement_recommendation": "Reduce filler words"
            }
          },
          "objection_handling": {
            "score": 70,
            "weight_pct": 15,
            "explanation": "Addressed budget objection but no follow-up probe",
            "insufficient_evidence": false,
            "metrics": {
              "objections_detected": ["budget"],
              "followup_probe_present": false,
              "resolution_check_present": true,
              "improvement_recommendation": "Add a follow-up question after handling objections"
            }
          },
          "cta": {
            "score": 82,
            "weight_pct": 15,
            "explanation": "Clear CTA with specific time offered",
            "insufficient_evidence": false,
            "metrics": {
              "cta_attempted": true,
              "cta_type": "meeting",
              "specific_time_offered": true,
              "improvement_recommendation": "Confirm next steps via email",
              "outcome": "accepted"
            }
          }
        },
        "gaps": {
          "skill": 25,
          "playbook": 15,
          "rationale": "Discovery needs more depth on timing and decision process"
        },
        "coaching": {
          "top_wins": ["Strong opener", "Good pitch tailoring"],
          "top_opportunities": ["Deeper discovery", "Objection follow-up probes"],
          "suggested_drills": [
            {
              "facet": "discovery",
              "assignment": "Practice SPIN questions for uncovering timeline"
            }
          ]
        }
      },
      "call_log": {
        "_id": "507f1f77bcf86cd799439022",
        "contact": {
          "first_name": "John",
          "last_name": "Doe",
          "company": "Acme Corp"
        },
        "recording_url": "https://recordings.example.com/call_abc123.mp3",
        "duration": 245
      },
      "user": {
        "_id": "507f1f77bcf86cd799439033",
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@company.com"
      },
      "type": "call",
      "createdAt": "2024-01-15T14:33:00.000Z",
      "updatedAt": "2024-01-15T14:33:00.000Z"
    }
  ],
  "pagination": {
    "total": 42,
    "page": 1,
    "limit": 10,
    "pages": 5
  }
}
```

### Response Fields

| Field       | Type   | Description                                                    |
| ----------- | ------ | -------------------------------------------------------------- |
| `_id`       | string | Unique identifier for the scored call                          |
| `insight`   | object | Full scoring insight (see below)                               |
| `call_log`  | object | Associated call log with contact, recording\_url, and duration |
| `user`      | object | User who made the call                                         |
| `type`      | string | Scoring type (`call`)                                          |
| `createdAt` | date   | Record creation time                                           |
| `updatedAt` | date   | Record last update time                                        |

#### Insight Object

| Field                | Type   | Description                                                                   |
| -------------------- | ------ | ----------------------------------------------------------------------------- |
| `total_score`        | number | Overall call score (0-100)                                                    |
| `lead`               | object | Lead qualification data (fit\_score, decision\_maker, lifecycle stage)        |
| `messaging`          | object | Messaging effectiveness (value props, objection outcomes, emotional triggers) |
| `targeting_feedback` | object | Persona and industry fit assessment                                           |
| `metadata`           | object | Call characteristics (duration, talk ratio, questions, speech rate)           |
| `facets`             | object | Six scoring categories with individual scores and evidence                    |
| `gaps`               | object | Skill and playbook gap scores with rationale                                  |
| `coaching`           | object | Top wins, opportunities, and suggested drills                                 |

#### Scoring Facets

| Facet                | Weight | Description                                              |
| -------------------- | ------ | -------------------------------------------------------- |
| `intro`              | 10%    | Permission opener usage and effectiveness                |
| `discovery`          | 25%    | Question quality, open question ratio, topic coverage    |
| `pitch`              | 20%    | Pitch duration, tailoring to discovery, outcome keywords |
| `tonality`           | 15%    | Speech rate, interruptions, filler word density          |
| `objection_handling` | 15%    | Objection detection, follow-up probes, resolution        |
| `cta`                | 15%    | CTA attempt, type, specificity, and outcome              |


## OpenAPI

````yaml GET /v1/scored-calls
openapi: 3.0.1
info:
  title: Salesfinity API
  description: API documentation for Salesfinity platform
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://client-api.salesfinity.co
security:
  - ApiKeyAuth: []
paths:
  /v1/scored-calls:
    get:
      tags:
        - Scored Calls
      description: >-
        Retrieves a paginated list of AI-scored calls with detailed insights,
        scoring facets, lead qualification, and coaching recommendations.
      operationId: get-scored-calls
      parameters:
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
          description: Items per page
        - name: sort
          in: query
          required: false
          schema:
            type: string
          description: 'Sort field(s). Prefix with - for descending. Default: -createdAt'
        - name: start_date
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Filter by start date (ISO 8601)
        - name: end_date
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Filter by end date (ISO 8601)
        - name: min_score
          in: query
          required: false
          schema:
            type: number
            minimum: 0
            maximum: 100
          description: Minimum total score
        - name: max_score
          in: query
          required: false
          schema:
            type: number
            minimum: 0
            maximum: 100
          description: Maximum total score
        - name: user_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by user ID
      responses:
        '200':
          description: Scored calls retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ScoredCallDTO'
                  pagination:
                    type: object
                    properties:
                      total:
                        type: integer
                      page:
                        type: integer
                      limit:
                        type: integer
                      pages:
                        type: integer
components:
  schemas:
    ScoredCallDTO:
      type: object
      properties:
        _id:
          type: string
          description: Unique identifier
        insight:
          type: object
          description: Full scoring insight
          properties:
            total_score:
              type: number
              description: Overall call score (0-100)
            lead:
              type: object
              properties:
                function:
                  type: string
                tech_stack_mentioned:
                  type: array
                  items:
                    type: string
                current_vendor:
                  type: string
                fit_score:
                  type: number
                is_decision_maker:
                  type: boolean
                is_correct_persona:
                  type: boolean
                pain_point_resonated:
                  type: boolean
                is_qualified_meeting:
                  type: boolean
                is_likely_to_buy:
                  type: boolean
                prospect_lifecycle_stage:
                  type: array
                  items:
                    type: string
            messaging:
              type: object
              properties:
                value_prop_resonated:
                  type: array
                  items:
                    type: string
                objection_outcome:
                  type: array
                  items:
                    type: string
                emotional_triggers:
                  type: array
                  items:
                    type: string
                recommendation_to_nail_messaging:
                  type: string
            targeting_feedback:
              type: object
              properties:
                persona_fit:
                  type: string
                industry_fit:
                  type: string
                persona_seniority:
                  type: string
                title_relevance:
                  type: string
                data_quality_issue:
                  type: array
                  items:
                    type: string
                future_follow_up_needed:
                  type: boolean
                follow_up_reason:
                  type: array
                  items:
                    type: string
            metadata:
              type: object
              properties:
                duration_sec:
                  type: number
                asr_confidence_avg:
                  type: number
                audio_features_available:
                  type: boolean
                talk_listen_ratio_rep:
                  type: number
                total_questions:
                  type: integer
                open_question_ratio:
                  type: number
                interruptions_by_rep:
                  type: integer
                core_pitch_duration_sec:
                  type: number
                estimated_wpm_rep:
                  type: number
                objections_detected:
                  type: array
                  items:
                    type: string
            facets:
              type: object
              properties:
                intro:
                  $ref: '#/components/schemas/ScoringFacet'
                discovery:
                  $ref: '#/components/schemas/ScoringFacet'
                pitch:
                  $ref: '#/components/schemas/ScoringFacet'
                tonality:
                  $ref: '#/components/schemas/ScoringFacet'
                objection_handling:
                  $ref: '#/components/schemas/ScoringFacet'
                cta:
                  $ref: '#/components/schemas/ScoringFacet'
            gaps:
              type: object
              properties:
                skill:
                  type: number
                playbook:
                  type: number
                rationale:
                  type: string
            coaching:
              type: object
              properties:
                top_wins:
                  type: array
                  items:
                    type: string
                top_opportunities:
                  type: array
                  items:
                    type: string
                suggested_drills:
                  type: array
                  items:
                    type: object
                    properties:
                      facet:
                        type: string
                      assignment:
                        type: string
        call_log:
          type: object
          properties:
            _id:
              type: string
            contact:
              type: object
            recording_url:
              type: string
            duration:
              type: number
        user:
          $ref: '#/components/schemas/UserDTO'
        type:
          type: string
          enum:
            - call
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - _id
        - insight
        - type
    ScoringFacet:
      type: object
      properties:
        score:
          type: number
          description: Facet score (0-100)
        weight_pct:
          type: number
          description: Weight percentage of this facet
        explanation:
          type: string
          description: Human-readable explanation
        insufficient_evidence:
          type: boolean
        evidence:
          type: array
          items:
            type: object
            properties:
              start_sec:
                type: number
              end_sec:
                type: number
              text:
                type: string
    UserDTO:
      type: object
      properties:
        _id:
          type: string
        email:
          type: string
        first_name:
          type: string
        last_name:
          type: string
      required:
        - _id
        - email
        - first_name
        - last_name
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````