# List unmatched items of all transfers
URL: https://musicapi.com/docs/reference/list-unmatched-items.md

`GET https://api.musicapi.com/public/transfers/unmatched`

Section: Managed Transfers.
Product: MusicAPI Managed Transfers.
Auth: Basic, DocsSession (any one of them). Use Basic with your Client ID and Client Secret from your server only.

The unmatched and failed items of every transfer of your account that finished in `[from, to)`, ordered by transfer and then by item. For a daily bulk pull. The window must not be longer than 31 days. A page can hold fewer rows than `limit` and still have a `nextCursor`: continue until `nextCursor` is `null`. Requires Client Secret authentication.

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | date-time | yes | A transfer is in the window when it finished at or after this time. |
| `to` | date-time | no | A transfer is in the window when it finished before this time. Default: now. |
| `reason` | notFound \\| lowConfidence \\| regionLocked \\| error \\| cannotMatch \\| limitReached | no | Return only the rows with this reason. `error` also returns the failed items. |
| `limit` | number | no | Rows per page. Default: `100`. |
| `cursor` | string | no | The `nextCursor` of the previous page. Leave it out for the first page. Opaque: do not build or change it. |

## Response 200

One page of rows.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `unmatched` | MatchResultRow[] | no |  |
| `unmatched[].transferUuid` | uuid | no |  |
| `unmatched[].title` | string | no |  |
| `unmatched[].artist` | string | no | The source artists, joined with a comma. |
| `unmatched[].playlistName` | string | no |  |
| `unmatched[].reason` | string | no | One of: notFound, lowConfidence, regionLocked, error, cannotMatch, limitReached. |
| `unmatched[].bestGuess` | string \| null | no | The best guess as one readable line. |
| `unmatched[].bestGuessUrl` | string \| null | no | The web address of the best guess on the destination service. Null when there is no guess or the service gives no address. |
| `unmatched[].status` | string | no | One of: unmatched, failed. |
| `unmatched[].itemType` | string | no | One of: track, album, artist. |
| `unmatched[].matchingPercentage` | number \| null | no |  |
| `unmatched[].source` | object | no |  |
| `unmatched[].source.id` | string | no | The id of the item on the source service. |
| `unmatched[].source.entryId` | string \| null | no | The id of the playlist entry, when the source service has one. |
| `unmatched[].source.name` | string | no |  |
| `unmatched[].source.artists` | string[] | no |  |
| `unmatched[].source.album` | string \| null | no |  |
| `unmatched[].source.isrc` | string \| null | no |  |
| `unmatched[].source.durationMs` | number \| null | no |  |
| `unmatched[].group` | object | no |  |
| `unmatched[].group.type` | string | no | One of: playlist, likedTracks, albums, artists, podcasts. |
| `unmatched[].group.name` | string | no |  |
| `unmatched[].group.sourceId` | string \| null | no | The source playlist id. Null for the other types. |
| `unmatched[].bestGuessCandidate` | object \| null | no | The closest item on the destination service. Not added. |
| `unmatched[].bestGuessCandidate.id` | string | no |  |
| `unmatched[].bestGuessCandidate.name` | string | no |  |
| `unmatched[].bestGuessCandidate.artists` | string[] | no |  |
| `unmatched[].bestGuessCandidate.album` | string \| null | no |  |
| `unmatched[].bestGuessCandidate.isrc` | string \| null | no |  |
| `unmatched[].bestGuessCandidate.url` | string \| null | no |  |
| `nextCursor` | string \| null | no | Send it back as `cursor`. `null` on the last page. |

```json
{
  "unmatched": [
    {
      "transferUuid": "5b0c6f0e-2c8a-4d0e-9a51-7e3f1c2d9b44",
      "title": "string",
      "artist": "string",
      "playlistName": "string",
      "reason": "notFound",
      "bestGuess": "string",
      "bestGuessUrl": "string",
      "status": "unmatched",
      "itemType": "track",
      "matchingPercentage": 0,
      "source": {
        "id": "string",
        "entryId": "string",
        "name": "string",
        "artists": [
          null
        ],
        "album": "string",
        "isrc": "string",
        "durationMs": 0
      },
      "group": {
        "type": "playlist",
        "name": "string",
        "sourceId": "string"
      },
      "bestGuessCandidate": {
        "id": "string",
        "name": "string",
        "artists": [
          null
        ],
        "album": "string",
        "isrc": "string",
        "url": "string"
      }
    }
  ],
  "nextCursor": "string"
}
```

## Errors

- 400: `from` is missing, `to` is not after `from`, the window is longer than 31 days, or the cursor is not valid.
- 401: The request has no credentials.
- 403: The request does not use Client Secret authentication, or the transfer service is not on for your account.

## Example

```bash
curl https://api.musicapi.com/public/transfers/unmatched \
  -u "$MUSICAPI_CLIENT_ID:$MUSICAPI_CLIENT_SECRET"
```