> ## Documentation Index > Fetch the complete documentation index at: https://docs.hihobbes.com/llms.txt > Use this file to discover all available pages before exploring further. # List Custom Link sessions > Return sessions and lifecycle timestamps associated with one Custom Link. Requires `custom_links:read` or `custom_links:write`. The response contains minimal session references, lifecycle stages, timestamps, and whether session analysis is available. It does not include transcripts, visitor identifiers, or prospect metadata. Retrieve full analyzed session detail with `GET /api/v1/sessions/{session_id}` and a `sessions:read` scope. ## OpenAPI ````yaml api-reference/openapi.json GET /api/v1/custom-links/{link_id}/sessions openapi: 3.1.0 info: title: Hobbes API description: > Use the Hobbes API to read your organization's analyzed demo sessions, prospects, accounts, transcripts, and funnel metrics, and to create and manage personalized Custom Links. **Authentication**: create an API key in Settings → API Keys, then send it as `Authorization: Bearer ` (or `x-api-key: `). Keys are org-scoped; responses only ever contain your organization's data. **Scopes**: keys carry scopes (`sessions:read`, `people:read`, `accounts:read`, `analytics:read`, `transcripts:read`, `custom_links:read`, `custom_links:write`). `custom_links:write` also satisfies read access. Raw transcript access is a separate opt-in scope with a daily quota. Existing API keys do not receive Custom Link scopes automatically. **Rate limits**: keys allow 120 requests per minute by default. Responses include `X-RateLimit-Limit` and `X-RateLimit-Remaining`; 429 responses include `Retry-After`. Transcript access has a separate quota of 2,000 reads per organization per UTC day. Custom Link mutations are limited to 10 requests per minute per organization. Creation and thumbnail rendering also use weighted hourly and daily organization quotas, so one request containing 500 links is one HTTP request but consumes up to 500 creation and 500 render units. **Support**: every response carries an `X-Request-ID` header. Include it when reporting an issue so we can find the exact request in our logs. **Stability**: changes within v1 are additive only. Fields may be added to responses; existing fields are never removed or renamed. version: 1.0.0 servers: - url: https://api-us.hihobbes.com description: Production security: - bearer: [] - apiKeyHeader: [] tags: - name: Sessions description: Analyzed demo sessions and their transcripts. - name: People description: Prospect profiles aggregated across sessions. - name: Accounts description: Company-level engagement rollups by email domain. - name: Metrics description: Aggregate funnel performance over a trailing window. - name: Custom Links description: Create and manage personalized links. - name: Custom Link Jobs description: Poll, cancel, and retry asynchronous Custom Link work. - name: Custom Link Campaigns description: Organize Custom Links into campaigns. paths: /api/v1/custom-links/{link_id}/sessions: get: tags: - Custom Links summary: List Custom Link sessions description: >- Return paginated session references and observed lifecycle timestamps for one Custom Link. Transcript content and visitor identifiers are not included. operationId: v1_list_custom_link_sessions parameters: - name: link_id in: path required: true schema: type: string format: uuid title: Link Id description: Custom Link UUID. description: Custom Link UUID. - name: limit in: query required: false schema: type: integer maximum: 200 minimum: 1 default: 50 title: Limit description: Number of records to return. Defaults to 50 and cannot exceed 200. description: Number of records to return. Defaults to 50 and cannot exceed 200. - name: offset in: query required: false schema: type: integer maximum: 1000000 minimum: 0 default: 0 title: Offset description: >- Zero-based number of records to skip. Use with `pagination.total` to request the next page. description: >- Zero-based number of records to skip. Use with `pagination.total` to request the next page. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/CustomLinkSessionsResponse' headers: X-Request-ID: description: Unique request identifier to include in support requests. schema: type: string example: req_01JABCDEF23456789 X-RateLimit-Limit: description: Request limit for this key in the current 60-second window. schema: type: integer example: 120 X-RateLimit-Remaining: description: Requests remaining for this key in the current window. schema: type: integer example: 119 '401': description: API key required or invalid. headers: X-Request-ID: description: Unique request identifier to include in support requests. schema: type: string example: req_01JABCDEF23456789 content: application/json: schema: type: object required: - detail properties: detail: type: string example: API key required or invalid. '403': description: API key does not include the required scope. headers: X-Request-ID: description: Unique request identifier to include in support requests. schema: type: string example: req_01JABCDEF23456789 content: application/json: schema: type: object required: - detail properties: detail: type: string example: API key does not include the required scope. '404': description: Custom Link not found in the key's organization. headers: X-Request-ID: description: Unique request identifier to include in support requests. schema: type: string example: req_01JABCDEF23456789 content: application/json: schema: type: object required: - detail properties: detail: type: string example: Custom Link not found in the key's organization. '422': description: A path, query, header, or request field failed validation. content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' headers: X-Request-ID: description: Unique request identifier to include in support requests. schema: type: string example: req_01JABCDEF23456789 '429': description: Rate limit or organization quota exceeded. headers: X-Request-ID: description: Unique request identifier to include in support requests. schema: type: string example: req_01JABCDEF23456789 X-RateLimit-Limit: description: Request limit for this key in the current 60-second window. schema: type: integer example: 120 X-RateLimit-Remaining: description: Requests remaining for this key in the current window. schema: type: integer example: 119 Retry-After: description: Seconds to wait before retrying. schema: type: integer example: 30 X-RateLimit-Reset: description: Unix timestamp when the limiting window resets. schema: type: integer content: application/json: schema: type: object required: - detail properties: detail: type: string example: Rate limit or organization quota exceeded. components: schemas: CustomLinkSessionsResponse: properties: sessions: items: $ref: '#/components/schemas/CustomLinkSessionReference' type: array title: Sessions total: type: integer title: Total limit: type: integer title: Limit offset: type: integer title: Offset type: object required: - sessions - total - limit - offset title: CustomLinkSessionsResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError CustomLinkSessionReference: properties: sessionId: type: string format: uuid title: Sessionid stage: $ref: '#/components/schemas/EngagementStage' openedAt: anyOf: - type: string format: date-time - type: 'null' title: Openedat startedAt: anyOf: - type: string format: date-time - type: 'null' title: Startedat engagedAt: anyOf: - type: string format: date-time - type: 'null' title: Engagedat endedAt: anyOf: - type: string format: date-time - type: 'null' title: Endedat analysisAvailable: type: boolean title: Analysisavailable default: false type: object required: - sessionId - stage title: CustomLinkSessionReference ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError EngagementStage: type: string enum: - not_opened - opened - started - engaged title: EngagementStage securitySchemes: bearer: type: http scheme: bearer description: Hobbes API key with the `hb_live_` prefix. apiKeyHeader: type: apiKey in: header name: x-api-key description: Alternative to the Bearer authorization header. ````