---
title: "Collateral Score Batch (status and results)"
method: GET
path: "/v1/vehicle/collateral-score/batch"
tags: ["Collateral Score"]
---

# Collateral Score Batch (status and results)

`GET /v1/vehicle/collateral-score/batch`

## Request

- Base URL: `https://api.carsxe.com`
- URL: `https://api.carsxe.com/v1/vehicle/collateral-score/batch`
- Auth: API key in query parameter `key`
- TypeScript: <https://skmtc.dev/carsxe/apis/carsxe-api/docs/v1/vehicle/collateral-score/batch/get.ts> (a function with typed inputs; its response is checked against the schema)

Batch progress, and every result in submission order once `status` is `completed`.

## Query parameters

- `batch_id` string, required

## Response `200`

Batch status.

- object
  - `success` boolean
  - `batch_id` string
  - `status` 'processing' | 'completed'
  - `total` integer
  - `processed` integer
  - `succeeded` integer
  - `failed` integer
  - `created_at` string, date-time
  - `completed_at` string, date-time, nullable
  - `results` union[]: Present once `status` is `completed`.
    - union
      - object
        - `index` integer
        - `success` true
        - `result` CollateralScoreResult
          - `vin` string
          - `vehicle` object
            - `year` integer, nullable
            - `make` string, nullable
            - `model` string, nullable
            - `trim` string, nullable
          - `current_values` object: Average-condition market values, adjusted for mileage and region.
            - `retail` integer, nullable
            - `wholesale` integer, nullable
            - `trade_in` integer, nullable
            - `msrp` integer, nullable
            - `confidence` 'high' | 'medium' | 'low'
            - `publish_date` string, nullable
          - `depreciation_forecast` object: `current_values.retail` projected by the ratio between today's and the horizon's points on a depreciation curve rebuilt monthly from market values (median retail ÷ MSRP by vehicle age).
            - `12_month` CollateralForecastPoint, nullable: `null` when the depreciation curve has no data that far out.
              - …
            - `24_month` CollateralForecastPoint, nullable: `null` when the depreciation curve has no data that far out.
              - …
            - `36_month` CollateralForecastPoint, nullable: `null` when the depreciation curve has no data that far out.
              - …
            - `48_month` CollateralForecastPoint, nullable: `null` when the depreciation curve has no data that far out.
              - …
            - `at_loan_maturity` CollateralForecastPoint, nullable: `null` when the depreciation curve has no data that far out.
              - …
            - `base_value` 'retail'
            - `curve_source` 'model' | 'segment' | 'null', nullable: `model` is this make/model's own curve; `segment` is its vehicle class average.
            - `curve_key` string, nullable
            - `curve_min_sample_size` integer, nullable: Fewest valuations behind any curve point the projections used.
            - `curve_refreshed_at` string, date-time, nullable
          - `depreciation_velocity` object
            - `percentile_vs_segment` integer, nullable: Share of models in the segment that lose value more slowly; lower is better.
            - `segment` string, nullable
            - `segment_name` string, nullable
            - `annual_depreciation_pct` number, nullable
            - `peer_count` integer
            - `interpretation` string, nullable
          - `risk_flags` object: `null` means the source was unavailable, not that the vehicle is clean.
            - `salvage_title` boolean, nullable
            - `flood_damage` boolean, nullable
            - `lemon_law_buyback` boolean, nullable
            - `odometer_anomaly` boolean, nullable
            - `other_title_brands` string[], nullable
            - `total_loss_reported` boolean, nullable
            - `open_recalls_high_severity` integer, nullable
            - `accident_count` integer, nullable: Always `null` for now; accident history is not yet available.
            - `total_flags` integer
          - `lending_recommendation` object
            - `risk_tier` 'A' | 'B' | 'C' | 'D'
            - `suggested_max_ltv` 120 | 110 | 95 | 80
            - `manual_review_recommended` boolean
            - `reasons` string[]
            - `rationale` string
            - `confidence` 'high' | 'medium' | 'low'
          - `data_gaps` string[]
      - object
        - `index` integer
        - `success` false
        - `vin` string
        - `status` integer: The HTTP status the single-VIN endpoint would have returned for this vehicle, or 503 when the vehicle could not be queued for scoring (resubmit it).
        - `message` string
        - `retryable` true: Present only when resubmitting this vehicle may succeed: its lookup failed with a retryable 502/504, or it could not be queued (503). Absent on every other failure.

## Other responses

- `400`: Missing `batch_id`.
- `401`: Missing API key, unknown/disabled API key, or inactive account.
- `404`: The collateral-score API is not enabled for this account, or no batch with this id exists for this account.

## Changes

- **2026-10-23** `ac8fcb028169`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/carsxe/apis/carsxe-api/changes/v1/vehicle/collateral-score/batch/get.md)

---

[API](https://skmtc.dev/carsxe/apis/carsxe-api.md) - [All operations](https://skmtc.dev/carsxe/apis/carsxe-api/llms.txt) - [OpenAPI document](https://skmtc.dev/carsxe/apis/carsxe-api/revisions/ed8f6c024239?raw)