> ## Documentation Index > Fetch the complete documentation index at: https://docs.matambaintelligence.com/llms.txt > Use this file to discover all available pages before exploring further. # List your events > Returns every change to your orders, oldest first, whether or not your webhook endpoint accepted it. We keep events for 30 days. Store the last `next_cursor` and pass it as `cursor` next time. ## OpenAPI ````yaml /openapi.json get /v1/events openapi: 3.1.0 info: title: Matamba Gateway version: '1' description: >- Open brokerage accounts for your customers, fund them from your wallet, place and track orders, and read each account's records at the broker. All amounts are integers in kobo, and every error includes a `code` you can use in your logic. servers: - url: https://{host} description: The sandbox and live environments each have their own host and API keys. variables: host: default: sandbox-host.invalid description: We send you the host along with your API keys. security: - bearer: [] tags: - name: Accounts description: The accounts you can trade for, and the broker's records for each one. - name: Orders description: >- Estimate, place, retrieve and cancel orders. We store each order before we send it to the exchange, and we send it only once. - name: Events description: >- Each change to your orders creates an event. We send the same event bodies to your webhook endpoint. See [Webhooks](/webhooks) for how to verify them. - name: Applications description: Open a brokerage account for your customer. - name: Reference description: Code lists from the broker that you use in account applications. - name: Wallet description: >- Your wallet, and the allocations you make from it to your customers' accounts. paths: /v1/events: get: tags: - Events summary: List your events description: >- Returns every change to your orders, oldest first, whether or not your webhook endpoint accepted it. We keep events for 30 days. Store the last `next_cursor` and pass it as `cursor` next time. operationId: listEvents parameters: - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Cursor' responses: '200': $ref: '#/components/responses/EventList' '400': $ref: '#/components/responses/Error' description: >- `invalid_request`: the request includes a parameter other than `limit` and `cursor`, a parameter sent twice, an empty parameter, or a cursor we didn't issue. '401': $ref: '#/components/responses/Error' description: '`unauthorized`' '429': $ref: '#/components/responses/Error' description: '`rate_limited`' '500': $ref: '#/components/responses/Error' description: '`internal_error`' '503': $ref: '#/components/responses/Error' description: '`service_unavailable`' components: parameters: Limit: name: limit in: query required: false description: The number of items to return. schema: type: integer minimum: 1 maximum: 100 default: 25 Cursor: name: cursor in: query required: false description: The `next_cursor` from the previous page, unchanged. schema: type: string responses: EventList: description: A page of events. headers: x-request-id: $ref: '#/components/headers/RequestId' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/EventList' example: object: list has_more: false next_cursor: ZXZ0XzI data: - object: event id: msg_1d9e4b7a0c2f6e8b3a5d7c90 type: order.pending timestamp: '2026-09-25T06:12:34Z' version: 1 data: object: order id: ord_62jxryztxctob7uopekg state: pending account: '1000000001' symbol: DANGCEM side: buy quantity: 10 type: market time_in_force: day price_kobo: null filled_quantity: 0 exchange_order_id: '100001' reason: null reject_reason: null created_at: '2026-09-25T06:12:34Z' updated_at: '2026-09-25T06:12:34Z' - object: event id: msg_5f0c2a9e7b1d4c3a8e6f0b12 type: order.filled timestamp: '2026-09-25T06:13:02Z' version: 2 data: object: order id: ord_62jxryztxctob7uopekg state: filled account: '1000000001' symbol: DANGCEM side: buy quantity: 10 type: market time_in_force: day price_kobo: null filled_quantity: 10 exchange_order_id: '100001' reason: null reject_reason: null created_at: '2026-09-25T06:12:34Z' updated_at: '2026-09-25T06:13:02Z' Error: description: >- An error. Use `error.code` in your logic. A path that doesn't exist returns 404 `not_found`, and a method the path doesn't support returns 405 `method_not_allowed` with an `Allow` header. headers: x-request-id: $ref: '#/components/headers/RequestId' Cache-Control: $ref: '#/components/headers/CacheControl' Retry-After: $ref: '#/components/headers/RetryAfter' WWW-Authenticate: $ref: '#/components/headers/WWWAuthenticate' Allow: $ref: '#/components/headers/Allow' content: application/json: schema: $ref: '#/components/schemas/Error' headers: RequestId: description: A unique identifier for this request. Include it when you contact us. schema: type: string CacheControl: description: Always `no-store`. schema: type: string const: no-store RetryAfter: description: >- The number of seconds to wait before you retry. Sent with 429 (`1`) and with 503 `settlement_lockout` (`60`). schema: type: integer WWWAuthenticate: description: 'Sent with 401: `Bearer realm="Matamba Gateway"`.' schema: type: string Allow: description: Sent with 405. Lists the methods the path supports. schema: type: string schemas: EventList: type: object required: - object - has_more - next_cursor - data properties: object: type: string const: list has_more: type: boolean next_cursor: type: - string - 'null' description: >- Pass this as `cursor` to get later events. An empty page returns the same cursor you sent. Null only when your first request returns no events. data: type: array items: $ref: '#/components/schemas/Event' Error: type: object required: - error properties: error: type: object required: - type - code - message - doc_url properties: type: type: string description: The category of the error. enum: - authentication_error - invalid_request_error - idempotency_error - order_error - application_error - wallet_error - limit_error - rate_limit_error - api_error code: type: string description: The error code. Use it in your logic; it doesn't change. enum: - unauthorized - not_found - method_not_allowed - unsupported_media_type - request_too_large - invalid_request - missing_required_field - unknown_account - duplicate_order - order_not_found - exchange_unavailable - order_not_sent - order_rejected - similar_order_unresolved - order_not_cancelable - cancel_unconfirmed - settlement_lockout - account_not_at_broker - exchange_error - application_rejected - duplicate_application - application_not_found - application_not_sent - wallet_too_low - allocation_rejected - duplicate_allocation - allocation_not_found - allocation_not_sent - rate_limited - unknown_symbol - limit_exceeded - service_unavailable - internal_error message: type: string description: >- A human-readable description of the error, for your logs. The wording can change. param: type: string description: >- The field, parameter or header that caused the error. Absent when the error isn't tied to a single field. reject_reason: type: string description: >- Why the exchange or broker rejected the request. Included with `order_rejected`, `application_rejected` and `allocation_rejected`, and takes the same values as the `reject_reason` field on the order, application or allocation. doc_url: type: string format: uri description: A link to the documentation for this error code. Event: type: object required: - object - id - type - timestamp - version - data properties: object: type: string const: event id: type: string description: >- Unique identifier for the event. Starts with `msg_`. Matches the `webhook-id` header the event was sent with. type: type: string pattern: ^order\.[a-z_]+$ description: >- `order.` followed by the state the change moved the order to, for example `order.filled`. timestamp: type: string format: date-time description: The order's `updated_at`. version: type: integer format: int64 description: Increases with every event and is never reused. data: $ref: '#/components/schemas/Order' Order: type: object required: - object - id - state - account - symbol - side - quantity - type - time_in_force - price_kobo - filled_quantity - exchange_order_id - reason - reject_reason - created_at - updated_at properties: object: type: string const: order id: type: string description: Unique identifier for the order. Starts with `ord_`. state: $ref: '#/components/schemas/OrderState' account: type: string description: The account code, in uppercase. symbol: type: string description: The symbol, in uppercase. side: type: string enum: - buy - sell quantity: type: integer format: int64 type: type: string enum: - limit - market time_in_force: type: string enum: - day - gtc - ioc - fok price_kobo: type: - integer - 'null' format: int64 description: The limit price in kobo. Null for a market order. filled_quantity: type: integer format: int64 description: The total number of shares traded so far. exchange_order_id: type: - string - 'null' description: The exchange's identifier for the order, once it has one. reason: type: - string - 'null' description: >- A sentence explaining the order's current state. It's for people to read, so don't use it in your logic. reject_reason: type: - string - 'null' description: >- Why the exchange rejected the order. Set only when `state` is `rejected`. enum: - insufficient_funds - market_closed - settlement_lockout - limit_orders_etf_only - unknown_symbol - symbol_not_tradable - account_not_at_broker - rejected_by_exchange - null created_at: type: string format: date-time description: In UTC, to the second. updated_at: type: string format: date-time description: In UTC, to the second. OrderState: type: string description: >- `sending`: stored, and the send is in progress. `pending`: the exchange has the order. `partially_filled`, `filled`: some or all of the order has traded. `uncertain`: we don't know whether the exchange received it. We don't send it again; we reconcile it against the exchange's record. `rejected`: the exchange rejected it; see `reject_reason`. `refused`: we refused it, and it never reached the exchange. `cancelled`: the exchange confirmed the cancel. `expired`: its time in force ran out. enum: - sending - pending - partially_filled - filled - uncertain - rejected - refused - cancelled - expired securitySchemes: bearer: type: http scheme: bearer description: >- `Authorization: Bearer `. Sandbox keys start with `mgw_test_` and live keys start with `mgw_live_`. Each key works only in its own environment, and a live key works only from the IP addresses or ranges registered for it. ````