Guides
Start typing to search…

Browse API

Systematic extraction of records

The Browse API provides a way to iterate through large datasets in selected partitions, 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

Browse API Reference

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.

{
    "perPage": 1000
}

Target Collection

Browsing targets a specific collection, such as Provider, Office, or Provider-Office relationships. Only one collection can be targeted per browsing session, which helps maintain consistency in filtering and property selection.

{
    // ..
    "collectionKeys": [
        "provider",
        "office",
        "provider-offive"
    ]
}

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 and relationships matching those filters will be returned.

{
    // ..
    "params": {
        "filter": {
            "eq": {
                "resources.<collection>.<property>": "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

{
    // ..
    "params": {
        // ...
        "properties": {
            "include": [
                "relationships.<collection>.<property>",
                "resource.<collection>.<property>"
            ],
            "exclude": [
                "relationships.<collection>.<property>",
                "resources.<collection>.<property>"
            ]
        }
    }
}


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.

{
    "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.

{
    // ..
    "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 Search API for user-facing, query-based 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.

Updated 3 days ago