Documentation Portal

TrendMiner offers two API endpoints for extracting context items. Which one to use depends on what you are trying to do.

Choose the right endpoint

"Which context items overlap with a specific time window?"

Use the Context Search endpoint: POST /context/v3/item/search. This is the same query the TrendMiner UI uses. You provide an event time interval and optional filters (keyword, component, context type, fields, labels, etc.) and get back context items whose time range overlaps with it. Use this when you are building a report, a dashboard, or any query tied to a specific process time window.

"What changed since my last sync?"

Use the Integration API endpoint: POST /integration/item/search (and its companion POST /integration/item/search/count). These endpoints filter by created or last-modified date and are optimized for incrementally syncing context items to an external system such as a data lake or BI tool. They do not require an event time interval.

Each endpoint uses a different database index optimized for its access pattern. Using the wrong endpoint will hit an unoptimized path and degrade performance at scale.

The rest of this guide covers the Integration API for sync use cases.

Authentication

All requests go to your TrendMiner instance's API. Authenticate with a Bearer token in the header:

Authorization: Bearer <your-token>
Content-Type: application/json

No specific role is required. However, a service or admin user sees all context items. Regular users only see items they have permission to access -- items outside their permissions are silently excluded from both results and counts.

Use a service or admin user for sync integrations. A regular user token will silently miss items, and your external system will have an incomplete copy.

Endpoints

Building a request

A minimal request body looks like this:

{
  "filters": [
    {
      "type": "LAST_MODIFIED_DATE_INTERVAL_FILTER",
      "startDate": "2026-06-01T00:00:00Z",
      "endDate": "2026-06-02T00:00:00Z"
    }
  ],
  "sortProperties": ["lastModifiedDate"],
  "sortDirection": "asc",
  "fetchSize": 60,
  "continuationToken": null
}

Fields

Date filters

Every request must include exactly one date filter. All timestamps use ISO-8601 format (e.g. 2026-06-01T00:00:00Z).

Interval filters -- match items within a date range (both boundaries inclusive):

Operator filters -- match items using a comparison operator:

Available operators: EQUAL, NOT_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, GREATER_THAN, GREATER_THAN_OR_EQUAL.

Reading the response

Search response (200)

{
  "content": [ ... ],
  "page": {
    "continuationToken": "abc123..."
  }
}

The content array contains the context items for this page. To fetch the next page, send the same request body with continuationToken set to the value from the response. Keep filters, sortProperties, and sortDirection identical across pages.

Note: the last page of results also returns a continuation token. Use the count endpoint first to know how many items to expect, so you can verify when all results have been returned.

Count response (200)

{
  "totalCount": 123
}

Handling errors

The 429 rate limit allows 5 concurrent calls to these endpoints by default. A request that cannot get a slot within 5 seconds is rejected.

Validation error details

A 400 response includes a body with error codes:

{
  "errorCode": "VALIDATION_FAILED",
  "details": {
    "0": [
      {
        "key": "filters",
        "message": { "code": "EXACTLY_ONE_METADATE_FILTER_REQUIRED" }
      }
    ]
  }
}

Common codes:

Setting up an incremental sync

The recommended pattern for keeping an external system up to date: