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

# Find file usages

> See which hubs, playlists, pieces, and pages directly reference a library file.

Before replacing or removing a Library file, inspect the stored relationships that use it:

```text theme={null}
GET /api/v1/teams/{team_id}/files/{id}/usages
```

For example, request the first 20 holders with a team token:

```bash theme={null}
curl --get 'https://api.member.dev/api/v1/teams/<team_id>/files/<file_id>/usages' \
  -H 'Authorization: Bearer <team_token>' \
  -H 'Accept: application/vnd.api+json' \
  --data-urlencode 'page[size]=20'
```

The route returns a JSON:API collection. Each `data` item is one **holder** of the file, with an `attributes.references` array describing the direct relationships to that holder. A *piece* in this guide means a **content node**: an item in a hub's structured content library. The response uses `usage_type: "content_node"` for a piece.

| `usage_type` | Holder | Example reference kinds |
| - | - | - |
| `hub` | Hub | `hub_media_file`, `hub_branding` |
| `playlist` | Media playlist | `playlist_item`, `playlist_attachment`, `hub_media_playlist` |
| `content_node` | Piece in a hub's content library | `content_node_media`, `content_node_attachment` |
| `page` | Hub page with a section attachment | `page_section_attachment` |

When the same holder refers to a file in more than one way, the response returns one holder resource with those references grouped together. Its JSON:API `id` is typed, such as `playlist:<playlist_id>`, so IDs from different holder types stay distinct. The API returns up to 50 references per holder. `reference_count` reports the total number found, and `references_truncated` is `true` when more than 50 references exist.

## Pagination and deleted items

Use `page[size]` to choose a page size from 1 to 100 (the default is 20). Follow the `links.next` URL from a response to continue; its opaque `page[after]` cursor keeps the holder ordering stable.

Soft-deleted holders and references are hidden by default. Set `include_deleted=true` to include them:

```text theme={null}
GET /api/v1/teams/{team_id}/files/{id}/usages?include_deleted=true&page[size]=50
```

For `page_section_attachment`, the reference-level `deleted` field reports whether that section is soft-deleted. The containing page has its own `deleted` field, so a deleted section can appear under a page that is still active. The file in the request must still be visible and active, and `include_deleted` does not expand a contact's existing access to active, owned hubs.

A holder inside a soft-deleted hub can have `deleted: false` and `hub_deleted: true`; check both fields before treating it as active.

This endpoint indexes persisted direct relationships only. It does not inspect page-builder JSON or infer transitive ancestors, and it excludes community profile and email references. It returns relationship metadata, not signed URLs or storage keys.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.