Query EPCIS Events

Documentation Index

Fetch the complete documentation index at: https://docs.closient.com/llms.txt

Use this file to discover all available pages before exploring further.

​

When to use

• A brand owner asks “where did batch X go?” — walk forward from bizStep=shipping events.
• A retailer needs to confirm a receive against the supplier’s shipping CTE — walk backward from bizStep=receiving.
• A compliance audit needs every CTE-relevant event for a GTIN in a date window for FSMA 204 § 1.1455(c) records request.
• Verify a recall: does the recalled batch have a corresponding disposition=recalled event in the ledger?

​

Auth

​

Flow

​

Step 1 — Pick filter dimensions

​

Step 2 — Issue the query

GET /epcis/api/2.0/events?MATCH_epc=https%3A%2F%2Fid.gs1.org%2F01%2F00614141123456%2F10%2FLOT-2026-042&EQ_bizStep=shipping
Authorization: Bearer <token>

​

Step 3 — Read the response

{
  "@context": ["https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld"],
  "type": "EPCISQueryDocument",
  "epcisBody": {
    "queryResults": {
      "eventList": [
        {
          "type": "ObjectEvent",
          "eventTime": "2026-05-18T14:30:00Z",
          "eventTimeZoneOffset": "+00:00",
          "epcList": ["https://id.gs1.org/01/00614141123456/10/LOT-2026-042"],
          "action": "OBSERVE",
          "bizStep": "shipping",
          "disposition": "in_transit",
          "readPoint": {"id": "https://id.gs1.org/414/0614141000005"}
        }
      ]
    }
  },
  "GS1-Next-Page-Token": "<opaque>"
}

​

Step 4 — Walk the cursor

GET /epcis/api/2.0/events?MATCH_epc=...&nextPageToken=<opaque>

​

Step 5 — Fetch a single event by ID

GET /epcis/api/2.0/events/{event_id}

​

Required inputs

​

Optional inputs

​

Output

• @context — EPCIS 2.0 context URI.
• type — always EPCISQueryDocument.
• epcisBody.queryResults.eventList — array of events (newest first).
• GS1-Next-Page-Token — present when more pages exist.

• 401 — missing or invalid auth.
• 403 — caller is not OWNER / MANAGER.
• 422 — malformed query parameters (e.g. unparsable timestamp).
• 429 — rate limited (300 req/min, 10k req/day per key).

​

Guidance for agents

• Read bizStep like a verb. The CBV vocabulary is human-readable on purpose: commissioning (born), harvesting (picked), cooling, packing, shipping, receiving, retail_selling, dispensing, destroying. Reconstruct narrative by sorting events by eventTime and reading the bizStep column.
• Disposition is current-state, bizStep is verb. A shipping event with disposition=in_transit means “we shipped it; it’s currently in transit.” A subsequent receiving with disposition=available means “the receiver took possession; it’s now available at their location.” A disposition=recalled event is what check-recalls looks for when answering “is this lot under recall?”.
• MATCH_epc is exact-string. The server matches the full EPC URI literally — https://id.gs1.org/01/00614141123456/10/LOT-A and https://id.gs1.org/01/00614141123456/10/LOT-A/21/0001 are different EPCs. Use MATCH_anyEPC (comma-separated) when you have multiple serialization candidates.
• Time windows narrow first. A query with no time bound has to scan the whole org’s event table. Always include GE_eventTime (and LT_eventTime when chasing a specific incident window) before fanning out to other dimensions.
• Chain reconstruction is sort-then-walk. EPCIS doesn’t natively give you the parent/child traversal that FSMA 204 expects (that lives on the materialized CTE rows). For a single-lot story, sort the returned events by eventTime and read the bizStep column; for full traversal of a CTE chain, use the /traceability/lots/{lot_id}/fda-export endpoint.
• Don’t reconstruct blast radius from this endpoint. Use GET /epcis/api/2.0/traceability/lots/{lot_id}/blast-radius — it walks the materialized CTE graph and returns aggregate counts in one call. Doing it by hand from event-level data is brittle (no parent/child linkage on raw events) and wastes API quota.

​

Known gaps (planned)

• No MASTER_DATA query. EPCIS 2.0 § 8.2.9 defines a master-data query (vocabulary lookup for biz locations, read points, etc.) — Closient does not implement it. Use the management API (/epcis/api/v1/trading-partners, /epcis/api/v1/reference-documents) for master data CRUD instead.
• No subscription / poll endpoint. EPCIS 2.0 § 8.3 standing-query subscription is not implemented. Agents must poll.
• No MATCH_epcClass filter. Class-level matches (all events on any EPC sharing a GTIN, regardless of lot/serial) require a pre-filter by MATCH_anyEPC or a post-query group-by on epcList. Planned alongside FSMA 204 GTIN-keyed dashboards.
• No EQ_quantity filter. Quantity-list-based filtering (events involving > N units) is out of scope for the standard SimpleEventQuery and not supported.
• Cursor opacity is server-internal. The GS1-Next-Page-Token is not the GS1-suggested base64-encoded eventID|eventTime form — it’s a Closient-internal opaque cursor. Tokens are not durable across schema migrations.

​

Related skills

• capture-epcis-event — write-side; produces the rows this skill reads.
• check-fsma-204-readiness — uses query results to determine which KDEs are present per lot.
• manage-recall — checks for disposition=recalled events when reviewing a recall record.
• check-recalls — consumer side; resolves “is GTIN X under recall right now?” via disposition=recalled (joined with the regulator recall feed).