> ## Documentation Index > Fetch the complete documentation index at: https://cal.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Get Discover listings by id > Returns published Discover listings by id, with the fields their public cards show: service name, provider, price, new-client discount, the provider's rating, review count and verification, duration, whether it is online, city, neighborhood and the business's time zone. With `includeNextAvailable`, also the earliest open slot in the next 7 days for the first 10 listings. Any id that is not a published listing is returned in `notFoundListingIds`. Requests with `includeNextAvailable` are limited to 60 per minute per user, shared across all of the user's API keys and access tokens. If accessed using an OAuth access token, the `EVENT_TYPE_READ` scope is required. ## OpenAPI ````yaml /api-reference/v2/openapi.json get /v2/discover/listings openapi: 3.0.0 info: title: Cal.com API v2 description: '' version: 1.0.0 contact: {} servers: [] security: [] tags: [] paths: /v2/discover/listings: get: tags: - Discover summary: Get Discover listings by id description: >- Returns published Discover listings by id, with the fields their public cards show: service name, provider, price, new-client discount, the provider's rating, review count and verification, duration, whether it is online, city, neighborhood and the business's time zone. With `includeNextAvailable`, also the earliest open slot in the next 7 days for the first 10 listings. Any id that is not a published listing is returned in `notFoundListingIds`. Requests with `includeNextAvailable` are limited to 60 per minute per user, shared across all of the user's API keys and access tokens. If accessed using an OAuth access token, the `EVENT_TYPE_READ` scope is required. operationId: DiscoverListingsController_getListings parameters: - name: ids required: true in: query description: >- Discover listing ids, such as the `listingId` values a Discover search returned. Repeat the parameter (`ids=12&ids=34`) or separate the ids with commas (`ids=12,34`). Duplicates are read once. schema: minItems: 1 maxItems: 50 example: - 12 - 34 type: array items: type: integer maximum: 2147483647 minimum: 1 - name: includeNextAvailable required: false in: query description: >- Also look up each listing's earliest open slot in the next 7 days. Only the first 10 listings are checked, so list the ones you care about first. schema: default: false example: true type: boolean - name: Authorization in: header description: >- value must be `Bearer ` where `` is api key prefixed with cal_, managed user access token, or OAuth access token required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/GetDiscoverListingsOutputResponseDto' '400': description: ids is missing, has more than 50 ids or a non-positive id '401': description: Unauthenticated '403': description: Insufficient permissions '429': description: >- Too many listing lookups with this credential, or more than 60 `includeNextAvailable` requests per minute for this user across all of their credentials components: schemas: GetDiscoverListingsOutputResponseDto: type: object properties: status: enum: - success - error type: string example: success data: $ref: '#/components/schemas/GetDiscoverListingsData' required: - status - data GetDiscoverListingsData: type: object properties: listings: description: >- The published listings among the requested ids, in the order asked. Review text, addresses, coordinates, descriptions, bios, photos and contact details are never returned. type: array items: $ref: '#/components/schemas/DiscoverListingOutput' notFoundListingIds: example: - 56 description: >- Requested ids that are not a published listing: unknown, unpublished or hidden. type: array items: type: number required: - listings - notFoundListingIds DiscoverListingOutput: type: object properties: listingId: type: number example: 12 description: The Discover listing id. service: type: string example: Deep tissue massage description: The service's name, as its card shows it. provider: type: string nullable: true example: Riverside Massage description: The provider's name; null when the listing shows none. priceInCents: type: number nullable: true example: 9000 description: >- The price in the currency's minor unit; null when no price is listed, which is not free. currency: type: string example: usd description: The price's ISO 4217 currency code. price: type: string example: $90.00 description: >- The price as the card shows it: a formatted amount, `free`, or `not listed`. newClientDiscountPercent: type: number nullable: true example: 15 description: >- The discount, in percent, a new client gets when booking through Discover; null when none. rating: type: number nullable: true example: 4.8 description: The provider's aggregate rating out of 5; null when unrated. reviewCount: type: number nullable: true example: 132 description: How many reviews the rating is based on; null when unrated. verified: type: boolean example: true description: Whether the provider is verified. durationMinutes: type: number example: 60 description: The service's length in minutes. online: type: boolean example: false description: Whether the service is online rather than at a place. city: type: string nullable: true example: Austin description: >- The city the card shows; null for an online listing or one whose city is not shown. neighborhood: type: string nullable: true example: Zilker description: >- The neighborhood the card shows; null when none, or when city is null. timeZone: type: string nullable: true example: America/Chicago description: The business's IANA time zone; null when unknown. nextAvailableChecked: type: boolean example: true description: >- Only with `includeNextAvailable`: whether the earliest open slot was looked up. False past the first 10 listings. nextAvailableSlot: type: string nullable: true example: '2026-11-10T15:00:00.000Z' description: >- Only with `includeNextAvailable`: the ISO 8601 start of the earliest open slot in the next 7 days; null when none or not checked. required: - listingId - service - provider - priceInCents - currency - price - newClientDiscountPercent - rating - reviewCount - verified - durationMinutes - online - city - neighborhood - timeZone ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.