> ## Documentation Index > Fetch the complete documentation index at: https://docs.stardex.com/llms.txt > Use this file to discover all available pages before exploring further. # Get list by ID > Retrieve a single list by UUID with its paginated items. Items are paginated via `items_offset` and `items_limit` query parameters. Each item includes the referenced person or company details depending on the list type. ## OpenAPI ````yaml /api-reference/openapi-v1.json get /v1/lists/{id} openapi: 3.1.0 info: title: Stardex API (v1) version: 1.0.0 description: >- Stardex ATS API — manage candidates, jobs, companies, and recruiting workflows. servers: - url: https://api.stardex.ai description: Production API server security: - bearerAuth: [] tags: - name: Persons description: Manage person records — contacts, work history, and custom fields. - name: Jobs description: Manage job postings — pipeline stages, team members, and custom fields. - name: Candidates description: Manage candidate records and pipeline stage transitions. - name: Companies description: Browse and retrieve company records. - name: Lists description: Create, search, and retrieve saved person and company lists. - name: Person Activities description: Create and manage activity records (notes, emails, meetings) for persons. - name: Team Members description: List team members for use in search filters and assignments. - name: Custom Fields description: Retrieve custom field definitions and tag options for search filters. paths: /v1/lists/{id}: get: tags: - Lists summary: Get list by ID description: >- Retrieve a single list by UUID with its paginated items. Items are paginated via `items_offset` and `items_limit` query parameters. Each item includes the referenced person or company details depending on the list type. operationId: getListById parameters: - in: path name: id required: true schema: type: string description: List UUID - schema: type: - integer - 'null' minimum: 0 default: 0 description: Items to skip for pagination. Defaults to 0. required: false name: items_offset in: query - schema: type: integer minimum: 1 maximum: 100 default: 50 description: Max items to return (1–100). Defaults to 50. required: false name: items_limit in: query responses: '200': description: List fetched content: application/json: schema: $ref: '#/components/schemas/ListByIdResponse' example: success: true data: id: aaa11111-bbbb-cccc-dddd-eeeeeeee1111 name: Engineering Candidates Q2 list_type: persons is_public: true is_archived: false linked_job_id: fff66666-0000-1111-2222-333333336666 linked_person_id: null linked_organization_company_id: null item_count: 42 created_by: id: bbb22222-cccc-dddd-eeee-ffffffff2222 first_name: Jane last_name: Smith owners: - id: bbb22222-cccc-dddd-eeee-ffffffff2222 first_name: Jane last_name: Smith created_at: '2024-01-15T10:00:00Z' updated_at: '2024-05-20T14:30:00Z' items: - id: eee55555-ffff-0000-1111-222222225555 person: id: ccc33333-dddd-eeee-ffff-000000003333 first_name: John last_name: Doe linkedin_url: https://linkedin.com/in/johndoe company: null created_at: '2024-02-01T12:00:00Z' items_total: 42 '400': description: Validation error content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error '404': description: Resource not found content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error '500': description: Internal server error content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error components: schemas: ListByIdResponse: type: object properties: success: type: boolean enum: - true data: $ref: '#/components/schemas/ListDetail' required: - success - data ListDetail: type: object properties: id: type: string format: uuid description: Unique list UUID. name: type: string description: List name. list_type: type: string enum: - persons - companies description: 'Type of entities in this list: "persons" or "companies".' is_public: type: boolean description: Whether the list is visible to all team members. is_archived: type: boolean description: Whether the list has been archived. linked_job_id: type: - string - 'null' format: uuid description: Job UUID this list is linked to, if any. linked_person_id: type: - string - 'null' format: uuid description: Person UUID this list is linked to, if any. linked_organization_company_id: type: - string - 'null' format: uuid description: Company UUID this list is linked to, if any. item_count: type: number description: Number of non-deleted items in the list. created_by: type: - object - 'null' properties: id: type: string format: uuid description: Team member UUID. first_name: type: - string - 'null' description: Creator first name. last_name: type: - string - 'null' description: Creator last name. required: - id - first_name - last_name description: Team member who created the list. owners: type: array items: type: object properties: id: type: string format: uuid description: Team member UUID. Matches IDs from GET /v1/team-members. first_name: type: - string - 'null' description: Team member first name. last_name: type: - string - 'null' description: Team member last name. required: - id - first_name - last_name description: List owners. created_at: type: - string - 'null' description: ISO 8601 creation timestamp. updated_at: type: - string - 'null' description: ISO 8601 last-updated timestamp. items: type: array items: $ref: '#/components/schemas/ListItem' description: Paginated list items. items_total: type: number description: Total number of non-deleted items in the list. required: - id - name - list_type - is_public - is_archived - linked_job_id - linked_person_id - linked_organization_company_id - item_count - created_by - owners - created_at - updated_at - items - items_total ListItem: type: object properties: id: type: string format: uuid description: List item UUID. person: type: - object - 'null' properties: id: type: string format: uuid description: Person UUID. first_name: type: - string - 'null' description: First name. last_name: type: - string - 'null' description: Last name. linkedin_url: type: - string - 'null' description: Person LinkedIn URL. required: - id - first_name - last_name - linkedin_url description: Person data when list_type is "persons". Null for company lists. company: type: - object - 'null' properties: id: type: string format: uuid description: Company UUID. name: type: - string - 'null' description: Company name. required: - id - name description: Company data when list_type is "companies". Null for person lists. created_at: type: - string - 'null' description: ISO 8601 timestamp when the item was added. required: - id - person - company - created_at securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Authenticate with a Bearer token: API key, OAuth token, or session token. ````