> ## Documentation Index > Fetch the complete documentation index at: https://guide.withvayu.com/llms.txt > Use this file to discover all available pages before exploring further. # Query events by timestamp period and optional event name > Fetch events occurring within a specified timestamp range. An optional event name can be provided to further filter the events. ## OpenAPI ````yaml get /events openapi: 3.0.0 info: title: Vayu API version: 1.0.0 description: >- The Vayu API is a RESTful API that allows you to submit events for processing and storage & manage billing related entities. The API is secured using the Bearer Authentication scheme with JWT tokens. To obtain a JWT token, please contact Vayu at team@withvayu.com contact: email: dev@withvayu.com name: Vayu, Inc url: https://withvayu.com servers: - url: https://connect.withvayu.com description: Production server - url: https://staging-connect.withvayu.com description: Sandbox server security: [] tags: - name: auth description: >- The auth tag is used for endpoints related to authentication and authorization. - name: events description: The events tag is used for endpoints related to event ingestion. - name: customers description: The customers tag is used for endpoints related to customer management. - name: meters description: The meters tag is used for endpoints related to meter management. - name: contracts description: The contracts tag is used for endpoints related to contract management. - name: invoices description: The invoices tag is used for endpoints related to invoice management. - name: credits description: The credits tag is used for endpoints related to credit management. - name: webhooks description: The webhooks tag is used for endpoints related to webhook management. paths: /events: get: tags: - events summary: Query events by timestamp period and optional event name description: >- Fetch events occurring within a specified timestamp range. An optional event name can be provided to further filter the events. operationId: queryEvents parameters: - schema: $ref: '#/components/schemas/StartTime' required: true in: query name: startTime - schema: $ref: '#/components/schemas/EndTime' required: true in: query name: endTime - schema: $ref: '#/components/schemas/EventName' required: false in: query name: eventName - schema: $ref: '#/components/schemas/CustomerAlias' required: false in: query name: customerAlias - schema: $ref: '#/components/schemas/Limit' required: false in: query name: limit - schema: $ref: '#/components/schemas/Cursor' required: false in: query name: cursor responses: '200': $ref: '#/components/responses/QueryEventsResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '429': description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/RateLimitErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/InternalServerErrorResponse' security: - BearerAuthorizer: [] components: schemas: StartTime: type: string format: date-time EndTime: type: string format: date-time EventName: type: string minLength: 1 CustomerAlias: type: string minLength: 1 Limit: type: number minimum: 1 maximum: 1000 default: 10 Cursor: type: string ValidationErrorResponse: type: object properties: type: type: string enum: - invalid_request_error code: type: string description: Specific machine-readable error code message: type: string description: Human-readable error explanation param: type: string description: Single parameter that failed validation params: type: array items: type: object properties: param: type: string description: The parameter that failed validation message: type: string description: Why validation failed for this parameter required: - param - message description: Multiple parameters that failed validation required: - type - code - message UnauthorizedErrorResponse: type: object properties: type: type: string enum: - authentication_error code: type: string enum: - authentication_failed message: type: string description: Human-readable error explanation required: - type - code - message RateLimitErrorResponse: type: object properties: type: type: string enum: - rate_limit_error code: type: string enum: - rate_limit_exceeded message: type: string description: Human-readable error explanation required: - type - code - message InternalServerErrorResponse: type: object properties: type: type: string enum: - api_error code: type: string enum: - internal_error message: type: string description: Human-readable error explanation required: - type - code - message QueryEventsResponse: type: object properties: events: type: array items: type: object properties: name: type: string description: >- The distinctive label assigned to an event, serving as a critical identifier for categorizing and pricing events within the system's backend infrastructure. example: api_call timestamp: type: string description: >- The temporal marker denoting the exact moment of event occurrence. The timestamp is formatted as an ISO 8601 string and is expressed in Coordinated Universal Time (UTC). i.e. YYYY-MM-DDTHH:MM:SS.SSSZ format: date-time example: '2023-09-13T18:25:43.511Z' customerAlias: type: string minLength: 1 description: >- A pseudonymous or otherwise obfuscated identifier uniquely assigned to each customer. example: customer_12345 ref: type: string description: >- A universally unique identifier (UUID) or other form of high-entropy string serving as an immutable reference for each event entry. example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21 data: type: object nullable: true additionalProperties: nullable: true description: >- A schema-less JSON object encapsulating miscellaneous attributes and metrics associated with the event. example: key1: processing_duration key2: api_url id: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - name - timestamp - customerAlias - ref - id - createdAt - updatedAt total: type: number hasMore: type: boolean nextCursor: type: string required: - events - total - hasMore responses: QueryEventsResponse: description: response contains an array of events content: application/json: schema: $ref: '#/components/schemas/QueryEventsResponse' securitySchemes: BearerAuthorizer: type: http scheme: bearer bearerFormat: JWT ````