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. EQ_bizStep, EQ_disposition and MATCH_epc accept |-separated values to match any of several (EQ_bizStep=shipping|receiving); the other parameters take a single value. Matching is exact against the value as it was captured, so an event captured with the short form shipping is not found by the CBV URI form, and vice versa. 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. EQ_bizStep, EQ_disposition and MATCH_epc accept |-separated values to match any of several (EQ_bizStep=shipping|receiving); the other parameters take a single value. Matching is exact against the value as it was captured, so an event captured with the short form shipping is not found by the CBV URI form, and vice versa. 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 plan, Free included. The 403 epcis_query_not_available path is only reachable on workspaces where EPCIS has been switched off by support. The query is a read, so it keeps working while billing is past due, unpaid or cancelled. EPCIS query is enabled on request; where it is not enabled, the endpoint returns 503 {"error":"epcis_query_node_unavailable"} — contact support to enable it.

Query parameters

  • EQ_bizStep

    string

    Standard EPCIS query parameter — matches events whose bizStep equals the given CBV value (e.g. shipping, receiving); separate several values with | to match any of them. TracePass parses the parameter and applies it to your workspace's own event store — an empty value or an unsupported parameter returns 400.

  • 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. A value that cannot be parsed as a date returns 400.

  • MATCH_epc

    string

    Standard EPCIS query parameter — matches events whose epcList contains the given EPC (a TracePass passport Digital Link URI); separate several EPCs with | to match any of them.

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