TracePass
Get started
EPCIS 2.0

Query EPCIS events

The GS1 EPCIS 2.0 Query interface. Search captured supply-chain events with the standard EPCIS query parameter grammar — `EQ_bizStep`, `GE_eventTime`, `LT_eventTime`, `MATCH_epc`, `EQ_bizLocation`, and the rest of the `EQ_*` / `GE_*` / `LT_*` / `MATCH_*` family. Parameters are passed through verbatim to the EPCIS query interface, so any query the GS1 grammar allows works here unchanged.

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

Query EPCIS events

The GS1 EPCIS 2.0 Query interface. Search captured supply-chain events with the standard EPCIS query parameter grammar — `EQ_bizStep`, `GE_eventTime`, `LT_eventTime`, `MATCH_epc`, `EQ_bizLocation`, and the rest of the `EQ_*` / `GE_*` / `LT_*` / `MATCH_*` family. Parameters are passed through verbatim to the EPCIS query interface, so any query the GS1 grammar allows works here unchanged.

TracePass proxies the query to an OpenEPCIS query node and returns the result as a standards-valid `EPCISQueryDocument` (`Content-Type: application/ld+json`). 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 <api-key>`.

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/04012345000015/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/04012345000015/21/BP-48V-100-000001"],
            "action": "OBSERVE",
            "bizStep": "shipping"
          }
        ]
      }
    }
  }
}

Related endpoints