> ## Documentation Index > Fetch the complete documentation index at: https://docs.qoory.ai/llms.txt > Use this file to discover all available pages before exploring further. # List upcoming events > Fetch results from one deterministic global top-30 snapshot of eligible upcoming Web3 IRL events, ordered by start date and immutable ID before optional filters and the request limit. Dates and status are computed from the response as-of date. Use at most one location filter: city and country cannot be provided together. Sources, providers, copied descriptions, media, tags, relationship graphs, and ingestion fields are not exposed. ## OpenAPI ````yaml /openapi/public-v1.json get /v1/events/upcoming openapi: 3.1.0 info: title: Qoory Developer API version: 1.0.0-beta description: >- Authenticated, credit-metered REST API for bounded, public-safe intelligence from Qoory's curated entity graph. Responses use strict source-free DTOs and do not expose bulk entity listing endpoints. servers: - url: https://api.qoory.ai description: Qoory production API security: [] tags: - name: Search description: Resolve specific entities through bounded search and identity matching. - name: Discovery description: Explore curated, fixed-size Qoory snapshots without bulk entity listing. - name: Projects description: Fetch project identities and bounded project intelligence. - name: Funds description: >- Fetch fund identities, rankings, partners, and verified portfolio relationships. - name: People description: Fetch person identities, roles, and verified investment relationships. - name: Tokens description: Fetch token identities, market facts, tokenomics, and unlock windows. - name: Markets description: Fetch bounded crypto-market snapshots and visualisation data. - name: Stocks description: Fetch crypto-related stock identities, rankings, and curated news. - name: News description: Fetch Qoory-curated, source-free news summaries and entity links. - name: Narratives description: Fetch Qoory-curated market narratives and bounded timelines. - name: Events description: Fetch eligible Web3 event identities and upcoming-event snapshots. - name: X Accounts description: Fetch opaque Qoory-owned X-account references and eligible entity links. paths: /v1/events/upcoming: get: tags: - Events summary: List upcoming events description: >- Fetch results from one deterministic global top-30 snapshot of eligible upcoming Web3 IRL events, ordered by start date and immutable ID before optional filters and the request limit. Dates and status are computed from the response as-of date. Use at most one location filter: city and country cannot be provided together. Sources, providers, copied descriptions, media, tags, relationship graphs, and ingestion fields are not exposed. operationId: listUpcomingEvents parameters: - name: q in: query required: false description: >- Case-insensitive text to match within this endpoint's bounded candidate set. example: uniswap schema: type: string minLength: 2 maxLength: 120 - name: event_type in: query required: false description: Optional normalized Web3 event category. example: conference schema: type: string enum: - conference - hackathon - summit - side_event - name: city in: query required: false description: Case-insensitive city filter. Do not combine it with country. example: Singapore schema: type: string minLength: 1 maxLength: 120 description: City location filter. Do not provide country when city is set. - name: country in: query required: false description: Case-insensitive country filter. Do not combine it with city. example: Singapore schema: type: string minLength: 1 maxLength: 120 description: Country location filter. Do not provide city when country is set. - name: month in: query required: false description: UTC calendar month used to filter the fixed upcoming-event snapshot. example: 9 schema: type: integer minimum: 1 maximum: 12 - name: year in: query required: false description: >- Four-digit UTC calendar year used to filter the fixed upcoming-event snapshot. example: 2026 schema: type: integer minimum: 2000 maximum: 2100 - name: limit in: query required: false description: >- Maximum number of items to return. This API does not expose pagination for this operation. example: 10 schema: type: integer minimum: 1 maximum: 30 default: 10 responses: '200': description: Successful response. headers: Cache-Control: description: Developer API responses are not cacheable. schema: type: string enum: - no-store x-qoory-request-id: description: Public request id for support and usage correlation. schema: type: string minLength: 8 maxLength: 96 pattern: ^[A-Za-z0-9_.:-]{8,96}$ x-qoory-credits-used: description: Credits charged for the request, when metering ran. schema: type: string pattern: ^[0-9]+$ maxLength: 20 x-qoory-credits-remaining: description: Credits remaining after the request, when available. schema: type: string pattern: ^[0-9]+$ maxLength: 20 x-qoory-rate-limit: description: >- Stringified rate-limit metadata with limit, remaining, reset_at, and tier. schema: type: string maxLength: 512 content: application/json: schema: type: object additionalProperties: false properties: data: $ref: >- #/components/schemas/DeveloperApiUpcomingEventsResponseData description: Operation-specific response data. meta: type: object additionalProperties: false properties: request_id: type: string minLength: 8 maxLength: 96 pattern: ^[A-Za-z0-9_.:-]{8,96}$ credits_used: type: integer minimum: 0 credits_remaining: type: integer minimum: 0 rate_limit: type: object additionalProperties: false properties: limit: type: integer minimum: 0 remaining: type: integer minimum: 0 reset_at: type: string format: date-time tier: type: string enum: - free - pro - pro_plus - team - internal required: - limit - remaining - reset_at - tier required: - request_id description: Request correlation, credit, and rate-limit metadata. required: - data - meta example: data: kind: upcoming_events as_of: '2026-07-16' limit: 10 q: null event_type: conference city: Singapore country: null month: 9 year: 2026 results: - type: event id: token2049-singapore-2026 slug: token2049-singapore-2026 name: TOKEN2049 Singapore 2026 event_type: conference status: upcoming start_date: '2026-09-30' end_date: '2026-10-01' city: Singapore country: Singapore website_url: https://www.token2049.com/ meta: request_id: req_example credits_used: 2 credits_remaining: 98 rate_limit: limit: 30 remaining: 29 reset_at: '2026-06-26T00:00:00.000Z' tier: free '401': description: Missing or invalid API key. headers: Cache-Control: description: Developer API responses are not cacheable. schema: type: string enum: - no-store x-qoory-request-id: description: Public request id for support and usage correlation. schema: type: string minLength: 8 maxLength: 96 pattern: ^[A-Za-z0-9_.:-]{8,96}$ x-qoory-credits-used: description: Credits charged for the request, when metering ran. schema: type: string pattern: ^[0-9]+$ maxLength: 20 x-qoory-credits-remaining: description: Credits remaining after the request, when available. schema: type: string pattern: ^[0-9]+$ maxLength: 20 x-qoory-rate-limit: description: >- Stringified rate-limit metadata with limit, remaining, reset_at, and tier. schema: type: string maxLength: 512 content: application/json: schema: $ref: '#/components/schemas/DeveloperApiErrorEnvelope' example: error: code: INVALID_API_KEY message: The API key is invalid. meta: request_id: req_example credits_used: 0 credits_remaining: 100 rate_limit: limit: 30 remaining: 29 reset_at: '2026-06-26T00:00:00.000Z' tier: free '402': description: Insufficient credits. headers: Cache-Control: description: Developer API responses are not cacheable. schema: type: string enum: - no-store x-qoory-request-id: description: Public request id for support and usage correlation. schema: type: string minLength: 8 maxLength: 96 pattern: ^[A-Za-z0-9_.:-]{8,96}$ x-qoory-credits-used: description: Credits charged for the request, when metering ran. schema: type: string pattern: ^[0-9]+$ maxLength: 20 x-qoory-credits-remaining: description: Credits remaining after the request, when available. schema: type: string pattern: ^[0-9]+$ maxLength: 20 x-qoory-rate-limit: description: >- Stringified rate-limit metadata with limit, remaining, reset_at, and tier. schema: type: string maxLength: 512 content: application/json: schema: $ref: '#/components/schemas/DeveloperApiErrorEnvelope' example: error: code: INSUFFICIENT_CREDITS message: Not enough credits are available for this request. meta: request_id: req_example credits_used: 0 credits_remaining: 0 rate_limit: limit: 30 remaining: 29 reset_at: '2026-06-26T00:00:00.000Z' tier: free '403': description: API key is disabled, revoked, or missing the required scope. headers: Cache-Control: description: Developer API responses are not cacheable. schema: type: string enum: - no-store x-qoory-request-id: description: Public request id for support and usage correlation. schema: type: string minLength: 8 maxLength: 96 pattern: ^[A-Za-z0-9_.:-]{8,96}$ x-qoory-credits-used: description: Credits charged for the request, when metering ran. schema: type: string pattern: ^[0-9]+$ maxLength: 20 x-qoory-credits-remaining: description: Credits remaining after the request, when available. schema: type: string pattern: ^[0-9]+$ maxLength: 20 x-qoory-rate-limit: description: >- Stringified rate-limit metadata with limit, remaining, reset_at, and tier. schema: type: string maxLength: 512 content: application/json: schema: $ref: '#/components/schemas/DeveloperApiErrorEnvelope' example: error: code: FORBIDDEN message: The API key does not have the required scope. meta: request_id: req_example credits_used: 0 credits_remaining: 100 rate_limit: limit: 30 remaining: 29 reset_at: '2026-06-26T00:00:00.000Z' tier: free '422': description: Invalid request. headers: Cache-Control: description: Developer API responses are not cacheable. schema: type: string enum: - no-store x-qoory-request-id: description: Public request id for support and usage correlation. schema: type: string minLength: 8 maxLength: 96 pattern: ^[A-Za-z0-9_.:-]{8,96}$ x-qoory-credits-used: description: Credits charged for the request, when metering ran. schema: type: string pattern: ^[0-9]+$ maxLength: 20 x-qoory-credits-remaining: description: Credits remaining after the request, when available. schema: type: string pattern: ^[0-9]+$ maxLength: 20 x-qoory-rate-limit: description: >- Stringified rate-limit metadata with limit, remaining, reset_at, and tier. schema: type: string maxLength: 512 content: application/json: schema: $ref: '#/components/schemas/DeveloperApiErrorEnvelope' example: error: code: INVALID_REQUEST message: The request parameters are invalid. details: - path: limit message: Expected a value within the documented range. code: too_big meta: request_id: req_example credits_used: 0 credits_remaining: 100 rate_limit: limit: 30 remaining: 29 reset_at: '2026-06-26T00:00:00.000Z' tier: free '429': description: Rate limit exceeded. headers: Cache-Control: description: Developer API responses are not cacheable. schema: type: string enum: - no-store x-qoory-request-id: description: Public request id for support and usage correlation. schema: type: string minLength: 8 maxLength: 96 pattern: ^[A-Za-z0-9_.:-]{8,96}$ x-qoory-credits-used: description: Credits charged for the request, when metering ran. schema: type: string pattern: ^[0-9]+$ maxLength: 20 x-qoory-credits-remaining: description: Credits remaining after the request, when available. schema: type: string pattern: ^[0-9]+$ maxLength: 20 x-qoory-rate-limit: description: >- Stringified rate-limit metadata with limit, remaining, reset_at, and tier. schema: type: string maxLength: 512 Retry-After: description: Whole seconds to wait before retrying a rate-limited request. schema: type: string pattern: ^[0-9]+$ maxLength: 10 content: application/json: schema: $ref: '#/components/schemas/DeveloperApiErrorEnvelope' example: error: code: RATE_LIMITED message: Rate limit exceeded. meta: request_id: req_example credits_used: 0 credits_remaining: 100 rate_limit: limit: 30 remaining: 29 reset_at: '2026-06-26T00:00:00.000Z' tier: free '500': description: Internal server error. headers: Cache-Control: description: Developer API responses are not cacheable. schema: type: string enum: - no-store x-qoory-request-id: description: Public request id for support and usage correlation. schema: type: string minLength: 8 maxLength: 96 pattern: ^[A-Za-z0-9_.:-]{8,96}$ x-qoory-credits-used: description: Credits charged for the request, when metering ran. schema: type: string pattern: ^[0-9]+$ maxLength: 20 x-qoory-credits-remaining: description: Credits remaining after the request, when available. schema: type: string pattern: ^[0-9]+$ maxLength: 20 x-qoory-rate-limit: description: >- Stringified rate-limit metadata with limit, remaining, reset_at, and tier. schema: type: string maxLength: 512 content: application/json: schema: $ref: '#/components/schemas/DeveloperApiErrorEnvelope' example: error: code: INTERNAL_ERROR message: The request could not be completed. meta: request_id: req_example credits_used: 0 credits_remaining: 100 rate_limit: limit: 30 remaining: 29 reset_at: '2026-06-26T00:00:00.000Z' tier: free security: - bearerAuth: [] components: schemas: DeveloperApiUpcomingEventsResponseData: type: object additionalProperties: false properties: kind: type: string enum: - upcoming_events description: Stable response-shape discriminator. as_of: type: string format: date description: Public as of value for this record. limit: type: integer minimum: 1 maximum: 30 description: Maximum result count applied to this response. q: anyOf: - type: string minLength: 2 maxLength: 120 - type: 'null' description: Public q value for this record. event_type: anyOf: - type: string enum: - conference - hackathon - summit - side_event - type: 'null' description: Public event type value for this record. city: anyOf: - type: string minLength: 1 maxLength: 120 - type: 'null' description: Public city value for this record. country: anyOf: - type: string minLength: 1 maxLength: 120 - type: 'null' description: Public country value for this record. month: anyOf: - type: integer minimum: 1 maximum: 12 - type: 'null' description: Public month value for this record. year: anyOf: - type: integer minimum: 2000 maximum: 2100 - type: 'null' description: Public year value for this record. results: type: array items: $ref: '#/components/schemas/DeveloperApiUpcomingEvent' maxItems: 30 description: Bounded ordered records returned by this operation. required: - kind - as_of - limit - q - event_type - city - country - month - year - results title: Upcoming Events Response Data description: A bounded, chronologically ordered upcoming-event snapshot. DeveloperApiErrorEnvelope: type: object additionalProperties: false properties: error: type: object additionalProperties: false properties: code: type: string enum: - MISSING_API_KEY - INVALID_API_KEY - DISABLED_API_KEY - REVOKED_API_KEY - USER_SUSPENDED - FEATURE_DISABLED - CONFIGURATION_ERROR - FORBIDDEN - INVALID_REQUEST - RATE_LIMITED - INSUFFICIENT_CREDITS - NOT_FOUND - DATA_UNAVAILABLE - INTERNAL_ERROR description: Stable machine-readable error code. message: type: string description: Public-safe human-readable error message. details: $ref: '#/components/schemas/DeveloperApiValidationErrorDetails' description: Optional bounded validation details for an invalid request. required: - code - message description: Standard Developer API error object. meta: type: object additionalProperties: false properties: request_id: type: string minLength: 8 maxLength: 96 pattern: ^[A-Za-z0-9_.:-]{8,96}$ description: Public request identifier for support and usage correlation. credits_used: type: integer minimum: 0 description: Total credits charged for this request. credits_remaining: type: integer minimum: 0 description: Credits available after this request, when known. rate_limit: type: object additionalProperties: false properties: limit: type: integer minimum: 0 description: Maximum result count applied to this response. remaining: type: integer minimum: 0 description: Requests remaining in the active rate-limit window. reset_at: type: string format: date-time description: UTC timestamp when the active rate-limit window resets. tier: type: string enum: - free - pro - pro_plus - team - internal description: >- Rate-limit or trend tier, as defined by the containing schema. required: - limit - remaining - reset_at - tier description: Rate-limit metadata for the active request window. required: - request_id description: Request correlation, credit, and rate-limit metadata. required: - error - meta title: Error Envelope description: Standard error response shared by every Developer API operation. DeveloperApiUpcomingEvent: type: object additionalProperties: false properties: type: type: string enum: - event description: Stable entity or record-type discriminator. id: type: string minLength: 1 maxLength: 160 description: Stable Qoory identifier for this record. slug: type: string minLength: 1 maxLength: 160 description: Canonical Qoory slug for this entity. name: type: string minLength: 1 maxLength: 200 description: Canonical display name for this entity. event_type: type: string enum: - conference - hackathon - summit - side_event description: Public event type value for this record. status: type: string enum: - upcoming description: Public status value for this record. start_date: type: string format: date description: Calendar date for the record's start. end_date: anyOf: - type: string format: date - type: 'null' description: Calendar date for the record's end. city: anyOf: - type: string minLength: 1 maxLength: 120 - type: 'null' description: Public city value for this record. country: anyOf: - type: string minLength: 1 maxLength: 120 - type: 'null' description: Public country value for this record. website_url: type: string format: uri pattern: ^https?:// maxLength: 2048 description: >- Public HTTP(S) organizer website. Local, private-network, Luma, and source/provider URLs are excluded. required: - type - id - slug - name - event_type - status - start_date - end_date - city - country - website_url title: Upcoming Event description: One eligible event identity from the fixed upcoming-event snapshot. DeveloperApiValidationErrorDetails: anyOf: - type: array items: type: object additionalProperties: false properties: path: type: string maxLength: 160 pattern: ^[A-Za-z0-9_.:-]{1,160}$ description: Bounded input path associated with a validation issue. message: type: string maxLength: 500 description: Public-safe human-readable error message. code: type: string maxLength: 80 pattern: ^[A-Za-z0-9_]+$ description: Stable machine-readable error code. required: - path - message - code maxItems: 50 - type: object additionalProperties: false properties: formErrors: type: array items: type: string maxLength: 500 maxItems: 50 description: Validation messages that apply to the request as a whole. fieldErrors: type: object maxProperties: 50 propertyNames: type: string minLength: 1 maxLength: 160 pattern: ^[A-Za-z0-9_.:-]{1,160}$ additionalProperties: type: array items: type: string maxLength: 500 maxItems: 50 description: Validation messages grouped by bounded input field name. required: [] title: Validation Error Details description: Bounded validation issues for an invalid request. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Qoory API key description: Use the HTTP authentication scheme with a Qoory API key. ````