TracePass
Get started
EPCIS 2.0

Query EPCIS events

Search your captured supply-chain events using EPCIS 2.0 query parameters. Eight are supported: `EQ_bizStep`, `EQ_disposition`, `EQ_eventType`, `MATCH_epc`, `EQ_bizLocation`, `EQ_readPoint`, `GE_eventTime` and `LT_eventTime`. Values may be `|`-separated to match any of several (`EQ_bizStep=shipping|receiving`). Any other parameter returns `400` rather than being silently ignored, so a typo fails loudly instead of widening your result set.

GET/api/v1/epcis/events
Download OpenAPI 3.1
GET/api/v1/epcis/events

Query EPCIS events

Search your captured supply-chain events using EPCIS 2.0 query parameters. Eight are supported: `EQ_bizStep`, `EQ_disposition`, `EQ_eventType`, `MATCH_epc`, `EQ_bizLocation`, `EQ_readPoint`, `GE_eventTime` and `LT_eventTime`. Values may be `|`-separated to match any of several (`EQ_bizStep=shipping|receiving`). Any other parameter returns `400` rather than being silently ignored, so a typo fails loudly instead of widening your result set.

Results come back as a standards-valid `EPCISQueryDocument` (`Content-Type: application/ld+json`), newest first, and only ever include events your own workspace captured and approved. A response caps at 1000 events; if there were more, `X-TracePass-Result-Truncated: true` is set — narrow the window with `GE_eventTime` / `LT_eventTime` to page through. Counts as one read.

Plan gate: EPCIS query is included on every paid plan (and on Free against an empty index — useful for integration validation). The 403 `epcis_query_not_available` path is only reachable on workspaces whose `epcisCaptureEnabled` flag has been disabled via per-tenant override. A lapsed subscription returns `402`. The query node is provisioned on request rather than by default — until it is deployed for your workspace the endpoint returns `503 {"error":"epcis_query_node_unavailable"}`; contact support to have it stood up.

Query parameters

  • EQ_bizStep

    string

    Standard EPCIS query parameter — matches events whose `bizStep` equals the given CBV value (e.g. `shipping`, `receiving`). Passed through verbatim to the EPCIS query interface.

  • GE_eventTime

    string (ISO 8601)

    Standard EPCIS query parameter — matches events whose `eventTime` is greater than or equal to the given timestamp. Pair with `LT_eventTime` for a window. Passed through verbatim.

  • MATCH_epc

    string

    Standard EPCIS query parameter — matches events whose `epcList` contains the given EPC (a TracePass passport Digital Link URI). Passed through verbatim.

Headers

  • Authorizationrequired

    string

    `Bearer <token>` — either a `tp_` API key (Developer → API Keys; simplest, for server-to-server) or an OAuth 2.0 access token (Developer → OAuth Apps; for user-authorized apps, scoped + revocable). The Authentication page has the full OAuth flow and scope list.

    e.g. Bearer tp_REDACTED_xxxxxxxxxxxx

Request

# All shipping events for one passport in a time window
curl -sS -G https://app.tracepass.eu/api/v1/epcis/events \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \
  --data-urlencode "EQ_bizStep=shipping" \
  --data-urlencode "GE_eventTime=2026-01-01T00:00:00.000Z" \
  --data-urlencode "LT_eventTime=2026-06-01T00:00:00.000Z" \
  --data-urlencode "MATCH_epc=https://id.tracepass.eu/p/01/04012345000016/21/BP-48V-100-000001"

Response

{
  "@context": "https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld",
  "type": "EPCISQueryDocument",
  "schemaVersion": "2.0",
  "creationDate": "2026-05-09T12:00:00.000Z",
  "epcisBody": {
    "queryResults": {
      "resultsBody": {
        "eventList": [
          {
            "type": "ObjectEvent",
            "eventID": "ni:///sha-256;9f86d0...?ver=CBV2.0",
            "eventTime": "2026-05-09T11:58:00.000Z",
            "eventTimeZoneOffset": "+02:00",
            "epcList": ["https://id.tracepass.eu/p/01/04012345000016/21/BP-48V-100-000001"],
            "action": "OBSERVE",
            "bizStep": "shipping"
          }
        ]
      }
    }
  }
}

Related endpoints