---
title: Query EPCIS events
description: GS1 EPCIS 2.0 query endpoint. Search events via EQ_bizStep / GE_eventTime / MATCH_epc and the standard EPCIS query grammar. Returns an EPCISQueryDocument.
canonical: "https://www.tracepass.eu/docs/query-events"
locale: en
source: "https://www.tracepass.eu/docs/query-events"
---

# Query EPCIS events

> GS1 EPCIS 2.0 query endpoint. Search events via EQ_bizStep / GE_eventTime / MATCH_epc and the standard EPCIS query grammar. Returns an EPCISQueryDocument.

```http
GET /api/v1/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.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Authorization` | header | string | yes | `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. |
| `EQ_bizStep` | query | string | no | 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` | query | string (ISO 8601) | no | 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` | query | string | no | Standard EPCIS query parameter — matches events whose `epcList` contains the given EPC (a TracePass passport Digital Link URI). Passed through verbatim. |

## Examples

```bash
# 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"
```

```typescript
const url = new URL("https://app.tracepass.eu/api/v1/epcis/events");
url.searchParams.set("EQ_bizStep", "shipping");
url.searchParams.set("GE_eventTime", "2026-01-01T00:00:00.000Z");
url.searchParams.set("LT_eventTime", "2026-06-01T00:00:00.000Z");
url.searchParams.set(
  "MATCH_epc",
  "https://id.tracepass.eu/p/01/04012345000016/21/BP-48V-100-000001",
);

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.TRACEPASS_API_KEY}` },
});
if (res.status === 503) throw new Error("Query node not provisioned");
const queryDocument = await res.json(); // EPCISQueryDocument
```

```python
import os, requests

res = requests.get(
    "https://app.tracepass.eu/api/v1/epcis/events",
    headers={"Authorization": f"Bearer {os.environ['TRACEPASS_API_KEY']}"},
    params={
        "EQ_bizStep": "shipping",
        "GE_eventTime": "2026-01-01T00:00:00.000Z",
        "LT_eventTime": "2026-06-01T00:00:00.000Z",
        "MATCH_epc": "https://id.tracepass.eu/p/01/04012345000016/21/BP-48V-100-000001",
    },
)
res.raise_for_status()
query_document = res.json()  # EPCISQueryDocument
```

## Responses

### 200 — OK

```json
{
  "@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"
          }
        ]
      }
    }
  }
}
```

### 401 — Missing API key

```json
{ "error": "Missing or invalid API key" }
```

### 402 — Subscription required

```json
{ "error": "Active paid subscription required" }
```

### 403 — Add-on not enabled

```json
{ "error": "epcis_query_not_available" }
```

### 503 — Query node unavailable

```json
{ "error": "epcis_query_node_unavailable" }
```

## Related

- [Capture EPCIS events](https://www.tracepass.eu/docs/capture-events.md)
- [Export a passport's EPCIS events](https://www.tracepass.eu/docs/passport-epcis-export.md)