# list_scores (/reference/list-scores)



Use it to find a score's `model_id`, or to check whether a score you need already exists.

## GET https://api.finic.ai/v1/scores

Lists your organization's scores, newest first (up to 500), with what each predicts and when it was last calibrated. Use it to find a score's `model_id`.

Authorization: `Bearer <API key>` (see [Authentication](/authentication)).

### Responses

- **200**: The organization's scores.

| Field | Type | Always | Description |
| --- | --- | --- | --- |
| `scores` | array of object | yes | Your scores, newest first. |
| `scores[].model_id` | string | yes | The score's id, `scm_…`. |
| `scores[].status` | `training`, `ready`, `failed` | yes | `training` while it's being created, `ready` to score records, `failed` if creating it failed (create it again). |
| `scores[].criteria` | string | yes | What the score predicts, in words. It's the `description` you gave when creating it, or, if you gave none, one Finic wrote from your examples. |
| `scores[].created_at` | string | yes | When the score was created. |
| `scores[].calibrated_at` | string or null | yes | When it was last [calibrated](/reference/calibrate), or `null` if never. |
| `scores[].examples` | integer | yes | The number of examples it was created from. |
| `scores[].bad_rate` | number | yes | The share of those examples with `is_bad` true, 0 to 1. |
| `scores[].scored` | integer | yes | The number of records [scored](/reference/score) with it. |
| `scores[].outcomes` | integer | yes | The number of those records with an outcome sent to calibrate. |

```json
{
  "scores": [
    {
      "model_id": "scm_01M4XRC000RT2GZSKYPD8J86G9",
      "status": "ready",
      "criteria": "Card-not-present payments. is_bad: the payment was charged back as fraud within 90 days.",
      "created_at": "2026-10-20T17:04:11Z",
      "calibrated_at": "2026-10-24T09:30:52Z",
      "examples": 1800,
      "bad_rate": 0.062,
      "scored": 41250,
      "outcomes": 3900
    }
  ]
}
```

- **401**: `authentication_error`: the API key is missing, unknown, revoked or expired.

- **429**: `rate_limited`: over the organization's [request rate](/reference#rate-limits). Retry with backoff.