> ## 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. # Query EPCIS events > Query events using EPCIS 2.0 SimpleEventQuery parameters (GS1 EPCIS 2.0 §8.2.7 and §8.2.8). Filter by event type, time window, CBV business step or disposition, read point, business location, action, or by EPC reference. Results are returned as a JSON-LD ``EPCISQueryDocument`` (§8.2.5) with the standard ``@context``, ``type``, and ``epcisBody.queryResults.eventList`` envelope. Cursor pagination uses the ``GS1-Next-Page-Token`` body field — pass it back as ``nextPageToken`` to fetch the next page. Caller must hold OWNER or MANAGER on an organization; results are scoped to events captured by that organization. ## OpenAPI ````yaml /openapi/openapi-epcis.json get /epcis/api/2.0/events openapi: 3.1.0 info: title: EPCIS 2.0 API version: 2.0.0 description: > GS1-conformant EPCIS 2.0 event capture and query API. ## Authentication All endpoints require an API key passed via the `X-API-Key` HTTP header, unless otherwise noted. ``` X-API-Key: csb__ ``` Generate API keys in **Settings > API Keys** in your dashboard, or via the Account API. Session-based (cookie) authentication is also accepted for browser-based access. ## Rate Limits | Tier | Requests / minute | Requests / day | |-------------|-------------------|----------------| | Default | 300 | 10,000 | | Custom | Contact us | Contact us | Rate-limit headers are included on every response so callers can self-throttle without hitting our 429s ("informed governor"): - `RateLimit-Policy` — every active window, e.g. `300;w=60, 10000;w=86400` - `RateLimit-Limit` — quota for the **most-restrictive** currently-active window - `RateLimit-Remaining` — requests left in that window - `RateLimit-Reset` — seconds until that window resets (relative; clock-skew safe) Legacy `X-RateLimit-*` aliases are also emitted for back-compat. `X-RateLimit-Reset` keeps the absolute Unix-timestamp shape to avoid breaking existing consumers. When rate-limited, you receive `429 Too Many Requests` with a `retry_after_seconds` field in the error envelope and a `Retry-After` header. ## Pagination List endpoints return paginated results in this envelope: ```json { "data": [...], "pagination": { "page": 1, "page_size": 25, "total_count": 342, "total_pages": 14, "has_next": true, "has_previous": false } } ``` Use `?page=2&page_size=50` query parameters. Maximum page size is 100. ## Error Responses All errors conform to [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457) with `Content-Type: application/problem+json`: ```json { "type": "https://closient.com/docs/errors/not_found", "title": "Not Found", "status": 404, "detail": "The requested resource was not found.", "error_code": "not_found", "retryable": false, "timestamp": "2026-03-31T12:00:00+00:00" } ``` Common error codes: `unauthorized` (401), `forbidden` (403), `not_found` (404), `validation_error` (422), `rate_limited` (429), `internal_error` (500). termsOfService: https://www.closient.com/terms/ servers: - url: https://www.closient.com security: [] externalDocs: description: Closient Documentation url: https://docs.closient.com paths: /epcis/api/2.0/events: get: tags: - EPCIS 2.0 summary: Query EPCIS events description: >- Query events using EPCIS 2.0 SimpleEventQuery parameters (GS1 EPCIS 2.0 §8.2.7 and §8.2.8). Filter by event type, time window, CBV business step or disposition, read point, business location, action, or by EPC reference. Results are returned as a JSON-LD ``EPCISQueryDocument`` (§8.2.5) with the standard ``@context``, ``type``, and ``epcisBody.queryResults.eventList`` envelope. Cursor pagination uses the ``GS1-Next-Page-Token`` body field — pass it back as ``nextPageToken`` to fetch the next page. Caller must hold OWNER or MANAGER on an organization; results are scoped to events captured by that organization. operationId: apps_epcis_api_epcis_query_events parameters: - in: query name: eventType schema: anyOf: - $ref: '#/components/schemas/EventTypeEnum' - type: 'null' description: >- Filter by EPCIS event type. One of ``ObjectEvent``, ``AggregationEvent``, ``TransactionEvent``, ``TransformationEvent``, or ``AssociationEvent`` per GS1 EPCIS 2.0 §7.3. required: false description: >- Filter by EPCIS event type. One of ``ObjectEvent``, ``AggregationEvent``, ``TransactionEvent``, ``TransformationEvent``, or ``AssociationEvent`` per GS1 EPCIS 2.0 §7.3. - in: query name: GE_eventTime schema: anyOf: - format: date-time type: string - type: 'null' description: >- Events with ``eventTime >= this value`` (inclusive lower bound). ISO-8601 / RFC 3339 with timezone offset per GS1 EPCIS 2.0 §8.2.7.2. title: Ge Eventtime required: false description: >- Events with ``eventTime >= this value`` (inclusive lower bound). ISO-8601 / RFC 3339 with timezone offset per GS1 EPCIS 2.0 §8.2.7.2. - in: query name: LT_eventTime schema: anyOf: - format: date-time type: string - type: 'null' description: >- Events with ``eventTime < this value`` (exclusive upper bound). ISO-8601 / RFC 3339 with timezone offset per GS1 EPCIS 2.0 §8.2.7.2. title: Lt Eventtime required: false description: >- Events with ``eventTime < this value`` (exclusive upper bound). ISO-8601 / RFC 3339 with timezone offset per GS1 EPCIS 2.0 §8.2.7.2. - in: query name: EQ_bizStep schema: anyOf: - type: string - type: 'null' description: >- 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. title: Eq Bizstep required: false description: >- 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. - in: query name: EQ_disposition schema: anyOf: - type: string - type: 'null' description: >- 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. title: Eq Disposition required: false description: >- 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. - in: query name: EQ_readPoint schema: anyOf: - type: string - type: 'null' description: >- 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. title: Eq Readpoint required: false description: >- 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. - in: query name: EQ_bizLocation schema: anyOf: - type: string - type: 'null' description: >- 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. title: Eq Bizlocation required: false description: >- 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. - in: query name: MATCH_epc schema: anyOf: - type: string - type: 'null' description: >- 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. title: Match Epc required: false description: >- 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. - in: query name: MATCH_anyEPC schema: anyOf: - type: string - type: 'null' description: >- 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. title: Match Anyepc required: false description: >- 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. - in: query name: EQ_action schema: anyOf: - $ref: '#/components/schemas/ActionEnum' - type: 'null' description: >- 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. required: false description: >- 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. - in: query name: perPage schema: default: 30 description: >- Maximum number of events to return per page (1-100, default 30). When more results are available the response carries a ``GS1-Next-Page-Token`` field — pass it back as ``nextPageToken`` to fetch the next page. maximum: 100 minimum: 1 title: Perpage type: integer required: false description: >- Maximum number of events to return per page (1-100, default 30). When more results are available the response carries a ``GS1-Next-Page-Token`` field — pass it back as ``nextPageToken`` to fetch the next page. - in: query name: nextPageToken schema: anyOf: - type: string - type: 'null' description: >- Cursor token for the next page, copied verbatim from the previous response's ``GS1-Next-Page-Token``. Opaque to the client — do not construct or modify. title: Nextpagetoken required: false description: >- Cursor token for the next page, copied verbatim from the previous response's ``GS1-Next-Page-Token``. Opaque to the client — do not construct or modify. responses: '200': description: OK content: application/json: schema: additionalProperties: true title: Response type: object '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorOut' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorOut' '422': description: Unprocessable Content content: application/json: schema: $ref: '#/components/schemas/ErrorOut' '429': description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/ErrorOut' security: - APIKeyHeaderAuth: [] - OAuthTokenAuth: [] - SessionAuth: [] components: schemas: EventTypeEnum: description: |- EPCIS 2.0 event type discriminator (the JSON-LD ``type`` field). Mirrors :class:`apps.epcis.vocabulary.EventType`. Values match the GS1 EPCIS 2.0 specification (ISO/IEC 19987:2024 §7.3 — Event Types) exactly: each event sent on the wire MUST carry one of these five type tokens. They are PascalCase in the spec and on the wire (the JSON-LD form drops the ``epcis:`` prefix used in XML). enum: - ObjectEvent - AggregationEvent - TransactionEvent - TransformationEvent - AssociationEvent title: EventTypeEnum type: string ActionEnum: description: |- EPCIS 2.0 ``action`` field — what the event did to its EPCs. Mirrors :class:`apps.epcis.vocabulary.Action`. Per GS1 EPCIS 2.0 §7.4.2 (Common Event Fields → action), the only valid wire values are the three uppercase tokens below. Blank / absent ``action`` is valid for ``TransformationEvent`` only (no enum represents that — omit the field instead). enum: - ADD - OBSERVE - DELETE title: ActionEnum type: string ErrorOut: description: |- RFC 9457 Problem Details response. All API errors are returned in this format with Content-Type: application/problem+json. examples: - detail: The requested resource was not found. error_code: not_found retryable: false status: 404 timestamp: '2026-03-31T12:00:00+00:00' title: Not Found type: https://closient.com/docs/errors/not_found - detail: Validation error. details: - loc: - body - name msg: Field required type: missing error_code: validation_error retryable: false status: 422 timestamp: '2026-03-31T12:00:00+00:00' title: Validation Error type: https://closient.com/docs/errors/validation_error - detail: Rate limit exceeded. Please try again later. error_code: rate_limited retry_after: 31 retryable: true status: 429 timestamp: '2026-03-31T12:00:00+00:00' title: Rate Limited type: https://closient.com/docs/errors/rate_limited properties: type: description: URI reference identifying the error type. title: Type type: string title: description: Short human-readable summary of the error. title: Title type: string status: description: HTTP status code. title: Status type: integer detail: description: Human-readable explanation of this specific occurrence. title: Detail type: string error_code: description: Machine-readable error code (e.g. not_found, unauthorized). title: Error Code type: string retryable: default: false description: Whether retrying the same request can succeed. title: Retryable type: boolean timestamp: description: ISO 8601 timestamp of when the error occurred. title: Timestamp type: string retry_after: anyOf: - type: integer - type: 'null' description: Seconds to wait before retrying (when applicable). title: Retry After owner_action_required: anyOf: - type: boolean - type: 'null' description: Whether the error requires account owner intervention. title: Owner Action Required details: description: Additional context (validation errors, etc.). title: Details required: - type - title - status - detail - error_code - timestamp title: ErrorOut type: object securitySchemes: APIKeyHeaderAuth: type: apiKey in: header name: X-API-Key OAuthTokenAuth: type: http scheme: bearer SessionAuth: type: apiKey in: cookie name: sessionid ````