> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clinia.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Browse
> Iterate through large datasets in selected partitions using a cursor-based snapshot for consistent bulk extraction with filtering and property selection.
The **Browse API** provides a way to iterate through large datasets in selected partitions across resource, relationship, or object collections, while ensuring data integrity across requests. Unlike search-based queries, browsing is designed for systematic extraction of records, often in bulk, while applying filters and property selectors as needed.
## Endpoint
Access the complete API reference documentation for the Regisrty Browse endpoint, including all parameters, request/response schemas, and examples.
Access the complete API reference documentation for the Partition Browse endpoint, including all parameters, request/response schemas, and examples.
### Parameters
#### Page Size
Each Browse API request can return a configurable number of records. By default, the API returns 100 records per call. However, you can change this limit if you require larger or smaller batches (1000 maximum). Unlike a traditional pagination system, there is no page parameter. Instead, pagination is controlled entirely by the cursor.
```json JSON Request theme={null}
{
"perPage": 1000
}
```
#### Target Collection
Browsing targets a specific collection, such as Provider resources or Provider-Office relationships. Only one collection can be targeted per browsing session, which helps maintain consistency in filtering and property selection.
```json JSON Request theme={null}
{
// ..
"collectionKeys": ["provider", "office", "provider-office"]
}
```
#### Filters
You can refine the results by applying filters within the collection you are browsing. The API supports both logical operators (such as `and`, `or`) and equation operators (such as `eq`, `lt`, `gt`, `any`, `all`).
It’s important to note that filters only affect the current collection. For example, if you browse Collection X, your filters cannot restrict results based on linked Collection Y data.
As soon as filters are applied, only collection resources or relationships matching those filters will be returned.
```json JSON Request theme={null}
{
// ..
"params": {
"filter": {
"eq": {
"resources..": "123"
}
}
}
}
```
#### Property Selector
To optimize payload size, you can specify which properties should be returned for each record (Via Includes and Excludes). A property selector allows you to explicitly choose the fields you need, whether they are top-level record properties or nested resource properties.
This also works on contained properties, but not on clinia-managed meta & identifiers.
Includes: Once applied, only the selected properties are included in the response, while all others are excluded.
Excludes: Once applied, the selected properties are excluded from the response
```json JSON Request theme={null}
{
// ..
"params": {
// ...
"properties": {
"include": [
"relationships..",
"resources.."
],
"exclude": [
"relationships..",
"resources.."
]
}
}
}
```
#### Cursor (Snapshot ID)
When you start a browsing session with the first API call, the system returns a cursor, also referred to as a snapshot ID. This cursor serves as your position marker in the dataset:
* It is fixed for the entire session.
* You must pass it back with each subsequent call so the API knows where to resume. If not provided, the session will restart from the beginning
* The system tracks your progress internally and ensures you get the next batch of records without overlap.
* When the dataset has been fully consumed, the API response will no longer include a cursor.
* No other parameters under "params" must be provided when a cursor is active.
This design ensures consistency across calls, even if the underlying data changes while you are browsing.
```json JSON Response theme={null}
{
"hits": [
// ...
],
"meta": {
"cursor": "FGluY2x1ZGVfY29udGV4dF...teHZNM1ZXQQ==",
"total": 1234
}
}
```
Include the cursor from the initial response in each subsequent request to continue from where you left off.
```json JSON Request theme={null}
{
// ..
"params": {
"cursor": "FGluY2x1ZGVfY29udGV4dF...teHZNM1ZXQQ=="
}
}
```
***
## Best Practices
The Browse API is designed for systematic data extraction rather than real-time query scenarios. To maximize efficiency and maintain data integrity, consider the following guidelines:
### Use Cases
* Bulk Data Retrieval: Extracting large sets of records for offline processing, synchronization, or reporting.
* Data Warehousing & ETL: Feeding records into downstream pipelines while ensuring integrity across batches.
* System Integrity: Use when the exact dataset snapshot consistency matters more than freshness between calls.
### Not Recommended For
* Real-Time Search: Use the appropriate [Search API](/api-reference/search/search-resources-of-a-specific-collection-in-the-data-partition) (resources or relationships) for user-facing discovery.
* Sorting Needs: Browse results are system-defined and not ordered by collection or metadata.
* Cross-Collection Filtering: Filters apply only within a given collection, not across collections or to relationships.
### Pagination & Cursor Management
* Always **store and reuse the cursor** returned by the first call.
* A cursor remains valid for 5 minutes after the last use. Ensure timely follow-up calls to avoid session expiration.
* If a cursor expires, start a new browsing session from the beginning.
### Batching Strategy
* Use the **maximum page size (1,000)** only when necessary; smaller sizes reduce memory footprint and make error handling easier.
* For resilience, implement **retry logic** in case of network issues.
* If your workflow depends on completing the full dataset extraction, **persist cursors** between calls.