---
title: "Recalls scoped to a make:, model:, or model-year: ref"
method: GET
path: "/v2/recalls/entity/{ref}"
tags: ["recalls"]
---

# Recalls scoped to a make:, model:, or model-year: ref

`GET /v2/recalls/entity/{ref}`

## Request

- Base URL: `https://api.cardog.app`
- URL: `https://api.cardog.app/v2/recalls/entity/{ref}`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

## Path parameters

- `ref` string, required

## Query parameters

- `limit` integer

## Response `200`

Campaigns, with affected model-years scoped to the queried ref

- RecallsEntity
  - `ref` string, required: The queried entity ref (make:, model:, or model-year:)
  - `total` integer, required: Total campaigns for this entity. `recalls` may be shorter when capped by `limit`.
  - `recalls` object[], required
    - `ref` string, required: Entity ref ({domain}:{key}) in the "recall" domain. Example: "recall:tc/2024-123"
    - `authority` string, required: Issuing authority key: "tc" (Transport Canada) or "nhtsa". Other values may be added.
    - `authorityLabel` string, required: Display label, e.g. "Transport Canada"
    - `campaignNumber` string, required
    - `component` string, nullable, required
    - `defectSummary` string, nullable, required
    - `consequenceSummary` string, nullable, required
    - `correctiveAction` string, nullable, required
    - `recallDate` string, nullable, required: Date the recall was issued (ISO date, YYYY-MM-DD)
    - `notificationType` string, nullable, required
    - `unitsAffected` integer, nullable, required: Units affected by the whole campaign (the largest value across `affects`)
    - `affects` object[], required: Affected model years. When queried by entity, only that entity's model years are listed.
      - `modelYearRef` string, required: Entity ref ({domain}:{key}) in the "model-year" domain. Example: "model-year:toyota/rav4/2021"
      - `year` integer, required
      - `unitsAffected` integer, nullable, required
    - `links` object: Related resources, keyed by relation name, each a server-relative path. Example: {"recalls": "/v2/recalls/entity/model-year:toyota/rav4/2021"}
  - `links` object: Related resources, keyed by relation name, each a server-relative path. Example: {"recalls": "/v2/recalls/entity/model-year:toyota/rav4/2021"}

## Other responses

- `400`: Invalid request — grammar failure or unknown-but-well-formed refs, NAMED in `refs`/`details`, with nearest-ref `suggestions` where computable. Never a fuzzy fallback.
- `401`: No valid credential (API key, session, or internal token)
- `402`: Insufficient credits (free-tier hard stop; paid tiers bill overage instead)
- `429`: Per-minute rate limit exceeded
- `500`: Internal error

---

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