--- title: "List links" method: GET path: "/api/links/" tags: ["Links"] --- # List links `GET /api/links/` ## โ–ถ๏ธ Usage With the List Links method, you can: 1. List all links elated to your Belvo account (without using any query parameters). 2. Get the details of a specific `link.id` (using the `id` query parameter). ## ๐Ÿ“– Pagination This method returns a paginated response (default: 100 items per page). You can use the `page_size` query parameter to increase the number of items returned to a maximum of 1000 items. You can use the `page` query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article. ## ๐Ÿ”ฆ Filtering Responses Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article. ## Query parameters - `page_size` integer - `page` integer - `omit` string - `fields` string - `id` string, uuid - `id__in` string[] - `institution` string - `institution__in` string[] - `access_mode` 'single' | 'recurrent' - `created_at` string, date - `created_at__gt` string, date - `created_at__gte` string, date - `created_at__lt` string, date - `created_at__lte` string, date - `created_at__range` string[] - `created_by__not_in` string[] - `external_id` string - `external_id__in` string[] - `institution_user_id` string - `institution_user_id__in` string[] - `refresh_rate` string - `status` string - `status__in` string[] ## Response `200` Ok - object - `count` integer โ€” The total number of results in your Belvo account. - `next` string, uri, nullable โ€” The URL to next page of results. Each page consists of up to 100 items. If there are not enough results for an additional page, the value is `null`. In our documentation example, we use `{endpoint}` as a placeholder value. In production, this value will be replaced by the actual endpoint you are currently using (for example, `accounts` or `owners`). - `previous` string, uri, nullable โ€” The URL to the previous page of results. If there is no previous page, the value is `null`. - `results` Link[] โ€” Array of link objects. - `id` string, uuid โ€” Belvo's unique identifier for the current item. - `institution` string โ€” Belvo's name for the institution. - `access_mode` 'single' | 'recurrent' | 'null', nullable โ€” The link type. For more information, see our Links article. We return one of the following enum values: - `single` - `recurrent` - `null` - `last_accessed_at` string, date-time, nullable โ€” The ISO-8601 timestamp of Belvo's most recent successful access to the institution for the given link. - `created_at` string, date-time โ€” The ISO-8601 timestamp of when the data point was created in Belvo's database. - `external_id` string โ€” An additional identifier for the link, provided by you, to store in the Belvo database. **Cannot** include any Personal Identifiable Information (PII). **Must** be at least three characters long. If we identify that the identifier contains PII, we will force a `null` value. For more information, see our Link creation article. - `institution_user_id` string โ€” > ๐Ÿ“˜ Info > > Only applicable for links created **after 08-02-2022**. A unique 44-character string that can be used to identify a user at a given institution. ๐Ÿ“š Check out our Avoiding duplicated links DevPortal article for more information and tips on how to use it. - `status` 'valid' | 'invalid' | 'unconfirmed' | 'token_required' โ€” The current status of the link. For more information, see our Link article in the devportal. We return one of the following values: - `valid` - `invalid` - `unconfirmed` - `token_required` - `created_by` string, uuid โ€” The unique ID for the user that created this item. - `refresh_rate` '6h' | '12h' | '24h' | '7d' | '30d' | 'null', nullable โ€” The update refresh rate for the recurrent link. For more information, check out our recurrent link documentation in our DevPortal. We return one of the following enum values: - `6h` - `12h` - `24h` - `7d` (default) - `30d` (once a month) - `null` (for single links) - `credentials_storage` string โ€” Indicates whether or not to store credentials (and the duration for which to store the credentials). - For recurrent links, this is set to `store` by default (and cannot be changed). - For single links, this is set to `365d` by default. Can be either: - `store` to store credentials (until the link is deleted) - `nostore` to not store credentials - Any value between `1d` and `365d` to indicate the number of days you want the credentials to be stored. For more information, check out the credentials_storage section of our Data retention controls article. - `fetch_resources` string[] โ€” An array of resources that you will receive a historical update for. - `stale_in` string โ€” Indicates how long any user-derived data should be stored in Belvo's database for the link (both single and recurrent). For example, if you send through `90d`, Belvo will remove any data from its database relating to the user after 90 days. For more information, check out the stale_in section of our Data retention controls article. > ๐Ÿ“˜ Info > > Belvo will only remove data for links that have not been updated in the period you provide in `stale_in`. Belvo will only remove data for links that have not been updated in the period you provide in `stale_in`. By default Belvo stores user data for 365 days, unless the link is deleted. ## Other responses - `401` โ€” Unauthorized - `403` โ€” Access to Belvo API denied - `408` โ€” Request Timeout - `500` โ€” Unexpected Error --- [API](https://skmtc.net/belvo/apis/belvo-api-docs.md) ยท [All operations](https://skmtc.net/belvo/apis/belvo-api-docs/llms.txt) ยท [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/belvo/belvo-api-docs/revisions/e82dca4a4b97/schema)