Skip to main content
GET
Query EPCIS events naming one EPC

Authorizations

X-API-Key
string
header
required

Path Parameters

epc
string
required

An EPC, as an EPC URN or a GS1 Digital Link URI exactly as captured. A Digital Link's slashes may be sent as-is or percent-encoded.

Query Parameters

eventType
enum<string>

Filter by EPCIS event type. One of ObjectEvent, AggregationEvent, TransactionEvent, TransformationEvent, or AssociationEvent per GS1 EPCIS 2.0 §7.3.

Available options:
ObjectEvent,
AggregationEvent,
TransactionEvent,
TransformationEvent,
AssociationEvent
GE_eventTime
string<date-time>

Events with eventTime >= this value (inclusive lower bound). ISO-8601 / RFC 3339 with timezone offset per GS1 EPCIS 2.0 §8.2.7.2.

LT_eventTime
string<date-time>

Events with eventTime < this value (exclusive upper bound). ISO-8601 / RFC 3339 with timezone offset per GS1 EPCIS 2.0 §8.2.7.2.

EQ_bizStep
string

Filter by exact CBV business step. Accepts either the bare CBV token (shipping) or the URN-prefixed form (urn:epcglobal:cbv:bizstep:shipping); matching is exact-string against what was captured. The CBV 2.0 vocabulary is extensible — vendor-specific URNs are valid input.

Pattern: ^[^\x00]{0,}$
EQ_disposition
string

Filter by exact CBV disposition (state of objects after the event). Accepts either the bare CBV token (in_transit) or the URN-prefixed form (urn:epcglobal:cbv:disp:in_transit); matching is exact-string against what was captured. The CBV 2.0 vocabulary is extensible — vendor-specific URNs are valid input.

Pattern: ^[^\x00]{0,}$
EQ_readPoint
string

Filter by exact read point URI (where the event was observed) per GS1 EPCIS 2.0 §7.4.2 / CBV 2.0 §10. Accepts the GS1 Digital Link form (https://id.gs1.org/414/{gln}) or the legacy SGLN URN (urn:epc:id:sgln:{company}.{location}.{extension}); matching is exact-string against what was captured.

Pattern: ^[^\x00]{0,}$
EQ_bizLocation
string

Filter by exact business location URI (where the objects logically are after the event) per GS1 EPCIS 2.0 §7.4.2. Accepts the GS1 Digital Link form or the legacy SGLN URN — same encoding as EQ_readPoint. Matching is exact-string against what was captured.

Pattern: ^[^\x00]{0,}$
MATCH_epc
string

Filter events referencing this single EPC (per GS1 EPCIS 2.0 §8.2.7.2 MATCH_epc). Searches epcList, childEPCs, inputEPCList, and outputEPCList simultaneously. Accepts either GS1 Digital Link (https://id.gs1.org/01/{gtin14}/10/{lot}[/21/{serial}]) or the legacy SGTIN URN form.

Pattern: ^[^\x00]{0,}$
MATCH_anyEPC
string

Comma-separated list of EPCs; matches events referencing any one of them (per GS1 EPCIS 2.0 §8.2.7.2 MATCH_anyEPC). Each token is trimmed before matching. Use MATCH_epc for a single EPC.

Pattern: ^[^\x00]{0,}$
EQ_action
enum<string>

Filter by action. Per GS1 EPCIS 2.0 §7.4.2 the only valid values are ADD, OBSERVE, or DELETE (uppercase). Blank action is reserved for TransformationEvent and cannot be filtered on.

Available options:
ADD,
OBSERVE,
DELETE
perPage
integer
default:30

Maximum number of events to return per page (1-100, default 30). When more results are available the response carries a Link header with rel="next" — request that URL to fetch the next page.

Required range: 1 <= x <= 100
nextPageToken
string

Cursor for the next page. The Link header's next-page URL already carries it; opaque to the client — do not construct or modify.

Pattern: ^[^\x00]{0,}$

Response

OK

200 response body for GET /events: a JSON-LD EPCISQueryDocument.

@context
string[]
required

JSON-LD context; the EPCIS 2.0 context.

type
string
required

Always EPCISQueryDocument.

epcisBody
EPCISBodySchema · object
required

Envelope holding queryResults.eventList.

Example: