> ## Documentation Index > Fetch the complete documentation index at: https://api-docs.spott.io/llms.txt > Use this file to discover all available pages before exploring further. # List opportunities > Returns a list of opportunities. Uses cursor pagination. ## OpenAPI ````yaml /openapi-private.json get /opportunities openapi: 3.1.0 info: title: Spott API Reference version: '0.1' servers: - url: https://api.gospott.com security: [] tags: [] paths: /opportunities: get: tags: - Opportunities summary: List opportunities description: Returns a list of opportunities. Uses cursor pagination. operationId: getOpportunities parameters: - name: limit required: false in: query description: >- Maximum number of opportunities to return per page. Must be between 1 and 50. Defaults to 25. schema: example: 25 type: number - name: modifiedSince required: false in: query description: >- ISO 8601 datetime string to filter opportunities modified on or after this date. Useful for incremental syncing. schema: format: date-time example: '2024-01-01T00:00:00.000Z' type: string - name: companyIds required: false in: query schema: type: array items: type: string description: Filter opportunities by company IDs - name: cursor required: false in: query description: >- Opaque cursor string for pagination. Use the cursor value from the previous response to fetch the next page. Omit for the first page. schema: type: string responses: '200': description: >- Successfully retrieved opportunities. Returns items array with pagination info containing cursor for the next page. content: application/json: schema: $ref: '#/components/schemas/GetOpportunitiesResponseDto' '400': description: >- Bad request - invalid query parameters (e.g., limit out of range, invalid date format) content: application/json: schema: $ref: '#/components/schemas/ExceptionBaseDto' '401': description: Unauthorized - invalid or missing authentication content: application/json: schema: $ref: '#/components/schemas/ExceptionBaseDto' '500': description: Error response content: application/json: schema: $ref: '#/components/schemas/ExceptionBaseDto' security: - x-api-key: [] components: schemas: GetOpportunitiesResponseDto: type: object properties: items: type: array items: $ref: '#/components/schemas/OpportunityCursorBaseDto' pagination: type: object properties: cursor: $ref: '#/components/schemas/OpportunityCursorWireDto' hasMore: type: boolean required: - cursor - hasMore required: - items - pagination id: PrivateGetOpportunitiesResponseDto ExceptionBaseDto: type: object properties: status: type: integer minimum: -9007199254740991 maximum: 9007199254740991 message: type: string requestId: type: string required: - status - message - requestId id: ExceptionBaseDto OpportunityCursorBaseDto: type: object properties: id: type: string minLength: 1 name: $ref: '#/components/schemas/OpportunityNameTypeDto' description: $ref: '#/components/schemas/OpportunityDescriptionTypeDto' stage: $ref: '#/components/schemas/OpportunityStageTypeDto' company: $ref: '#/components/schemas/OpportunityCompanyTypeDto' owner: $ref: '#/components/schemas/OpportunityOwnerTypeDto' closeDate: $ref: '#/components/schemas/OpportunityCloseDateTypeDto' createdAt: $ref: '#/components/schemas/OpportunityCreatedAtTypeDto' clientTeam: $ref: '#/components/schemas/OpportunityClientTeamTypeDto' nextTaskDue: $ref: '#/components/schemas/OpportunityNextTaskDueTypeDto' locations: $ref: '#/components/schemas/OpportunityLocationsTypeDto' required: - id - name - description - stage - company - owner - closeDate - createdAt - clientTeam - nextTaskDue - locations id: PrivateOpportunityCursorBaseDto OpportunityCursorWireDto: anyOf: - type: object properties: modifiedAt: $ref: '#/components/schemas/DateISO' id: type: string required: - modifiedAt - id - type: 'null' id: PrivateOpportunityCursorWireDto type: string OpportunityNameTypeDto: type: object properties: viewType: type: string enum: - opportunityName name: type: string required: - viewType - name id: PrivateOpportunityNameTypeDto OpportunityDescriptionTypeDto: type: object properties: viewType: type: string enum: - opportunityDescription description: anyOf: - type: string - type: 'null' required: - viewType - description id: PrivateOpportunityDescriptionTypeDto OpportunityStageTypeDto: type: object properties: viewType: type: string enum: - opportunityStage stage: $ref: '#/components/schemas/OpportunityStageValueDto' required: - viewType - stage id: PrivateOpportunityStageTypeDto OpportunityCompanyTypeDto: type: object properties: viewType: type: string enum: - opportunityCompany company: $ref: '#/components/schemas/OpportunityCompanyValueDto' required: - viewType - company id: PrivateOpportunityCompanyTypeDto OpportunityOwnerTypeDto: type: object properties: viewType: type: string enum: - opportunityOwner owner: anyOf: - $ref: '#/components/schemas/UserBadgeDto' - type: 'null' required: - viewType - owner id: PrivateOpportunityOwnerTypeDto OpportunityCloseDateTypeDto: type: object properties: viewType: type: string enum: - opportunityCloseDate closeDate: $ref: '#/components/schemas/OpportunityCloseDateValueDto' required: - viewType - closeDate id: PrivateOpportunityCloseDateTypeDto OpportunityCreatedAtTypeDto: type: object properties: viewType: type: string enum: - opportunityCreatedAt createdAt: $ref: '#/components/schemas/DateISO' required: - viewType - createdAt id: PrivateOpportunityCreatedAtTypeDto OpportunityClientTeamTypeDto: type: object properties: viewType: type: string enum: - opportunityClientTeam clientTeam: type: array items: type: object properties: id: type: string minLength: 1 firstName: type: string lastName: type: string middleName: anyOf: - type: string - type: 'null' secondLastName: anyOf: - type: string - type: 'null' avatarUrl: anyOf: - type: string - type: 'null' candidateId: type: string minLength: 1 companyId: type: string minLength: 1 companyName: type: string companyLogoUrl: anyOf: - type: string - type: 'null' jobTitle: anyOf: - type: string - type: 'null' department: anyOf: - type: string - type: 'null' emails: type: array items: type: object properties: email: type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ purpose: anyOf: - type: string enum: - personal - work - type: 'null' isPrimary: type: boolean required: - email - purpose - isPrimary phoneNumbers: type: array items: type: object properties: phoneNumber: type: string purpose: anyOf: - type: string enum: - personal - work - type: 'null' isPrimary: type: boolean required: - phoneNumber - purpose - isPrimary required: - id - firstName - lastName - middleName - secondLastName - avatarUrl - candidateId - companyId - companyName - companyLogoUrl - jobTitle - department - emails - phoneNumbers required: - viewType - clientTeam id: PrivateOpportunityClientTeamTypeDto OpportunityNextTaskDueTypeDto: type: object properties: viewType: type: string enum: - opportunityNextTaskDue nextTaskDue: anyOf: - type: object properties: id: type: string minLength: 1 content: type: string dueDate: anyOf: - $ref: '#/components/schemas/DateISO' - type: 'null' required: - id - content - dueDate - type: 'null' required: - viewType - nextTaskDue id: PrivateOpportunityNextTaskDueTypeDto OpportunityLocationsTypeDto: type: object properties: viewType: type: string enum: - opportunityLocations locations: type: array items: $ref: '#/components/schemas/LocationDto' required: - viewType - locations id: PrivateOpportunityLocationsTypeDto DateISO: id: DateISO format: date-time anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ - type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ OpportunityStageValueDto: type: object properties: id: type: string minLength: 1 name: type: string order: type: number isOpen: type: boolean required: - id - name - order - isOpen id: PrivateOpportunityStageValueDto OpportunityCompanyValueDto: type: object properties: id: type: string minLength: 1 name: type: string required: - id - name id: PrivateOpportunityCompanyValueDto UserBadgeDto: type: object properties: id: type: string name: type: string avatarUrl: anyOf: - type: string - type: 'null' deactivatedAt: anyOf: - $ref: '#/components/schemas/DateISO' - type: 'null' required: - id - name - avatarUrl - deactivatedAt id: PrivateUserBadgeDto OpportunityCloseDateValueDto: type: object properties: target: anyOf: - $ref: '#/components/schemas/DateISO' - type: 'null' required: - target id: PrivateOpportunityCloseDateValueDto LocationDto: type: object properties: street1: anyOf: - type: string - type: 'null' street2: anyOf: - type: string - type: 'null' postalCode: anyOf: - type: string - type: 'null' city: anyOf: - type: string - type: 'null' region: anyOf: - type: string - type: 'null' state: anyOf: - type: string - type: 'null' country: anyOf: - type: string - type: 'null' rawCityCountry: anyOf: - type: string - type: 'null' latitude: anyOf: - type: number - type: 'null' longitude: anyOf: - type: number - type: 'null' formattedAddress: anyOf: - type: string - type: 'null' type: anyOf: - $ref: '#/components/schemas/LocationType' - type: 'null' required: - street1 - street2 - postalCode - city - region - state - country - rawCityCountry - latitude - longitude - formattedAddress - type id: PrivateLocationDto LocationType: type: string enum: - primary_home - secondary_home - primary_work - headquarters - regional_office id: LocationType securitySchemes: x-api-key: type: apiKey name: x-api-key in: header description: >- API key for authentication. Get your API key from Settings → API Keys in your Spott dashboard. ````