> ## Documentation Index > Fetch the complete documentation index at: https://empirical.run/docs/llms.txt > Use this file to discover all available pages before exploring further. # List KV entries > Lists unexpired entries in key order, optionally filtered by key prefix. Values are omitted unless `include_values=true`; a page with values ends early once it holds about 8 MB, so always follow `next_cursor`. ## OpenAPI ````yaml /api-reference/openapi.generated.json get /api/kv openapi: 3.1.0 info: title: Empirical API version: 1.0.0 description: Programmatic access to Empirical test runs, snoozes, and more. contact: name: Empirical url: https://empirical.run servers: - url: https://api.empirical.run security: - Bearer: [] tags: - name: Test Runs description: Trigger, list, and inspect end-to-end test runs. - name: Test Cases description: >- Browse the Playwright test cases synced from a project's repository and manage their tags. - name: Environments description: >- Named deployment targets (slug + Playwright project filters) a project's tests run against. - name: Snoozes description: Temporarily suppress known test failures for specific Playwright tests. - name: KV description: >- Project-scoped key-value store shared by test runs, shards and agent sessions. Every entry expires; conditional writes make it safe for locks. - name: Analytics description: Aggregated test-run, test-count and test-case analytics for a project. - name: Badges description: Public README status badge images (SVG) for project environments. - name: Failure Groups description: >- Durable, cross-run identities for failure modes, carrying the latest triage diagnosis. - name: Files description: >- Upload files of any type and get a link to use in tasks, sessions and messages. Agents should use the `upload_file` tool, which returns a project-wide `file@` handle (`` is the file `id` below). - name: Reporter Configuration description: Reporters a project can use in environment and run reporter configs. paths: /api/kv: get: tags: - KV summary: List KV entries description: >- Lists unexpired entries in key order, optionally filtered by key prefix. Values are omitted unless `include_values=true`; a page with values ends early once it holds about 8 MB, so always follow `next_cursor`. operationId: listKvEntries parameters: - schema: type: string pattern: ^[A-Za-z0-9._:-]{0,512}$ default: '' description: Only return keys that start with this prefix. required: false description: Only return keys that start with this prefix. name: prefix in: query - schema: type: string pattern: ^[A-Za-z0-9._:-]{1,512}$ description: Pass a previous page's `next_cursor` to continue listing. required: false description: Pass a previous page's `next_cursor` to continue listing. name: cursor in: query - schema: type: integer minimum: 1 maximum: 1000 default: 100 description: Maximum entries to return (max 1000). required: false description: Maximum entries to return (max 1000). name: limit in: query - schema: type: string enum: - 'true' - 'false' default: 'false' description: Include each entry's value. required: false description: Include each entry's value. name: include_values in: query responses: '200': description: A page of entries. content: application/json: schema: $ref: '#/components/schemas/KvListResponse' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: KV store not configured. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: KvListResponse: type: object properties: data: type: object properties: entries: type: array items: $ref: '#/components/schemas/KvEntry' next_cursor: type: string nullable: true description: Pass as `cursor` to load the next page; `null` at the end. required: - entries - next_cursor description: Response payload. required: - data ErrorResponse: type: object properties: data: nullable: true description: Always null for error responses. error: type: object properties: message: type: string description: Human-readable error message. required: - message description: Error details. required: - data - error KvEntry: type: object properties: key: type: string pattern: ^[A-Za-z0-9._:-]{1,512}$ description: >- Key, 1-512 characters from `A-Z a-z 0-9 . _ : -`. Use `:` to namespace keys, e.g. `pw-lock:1234:user-settings`. value: anyOf: - type: string - type: number - type: boolean - type: array items: nullable: true - type: object additionalProperties: nullable: true description: >- The stored JSON value. Omitted from list responses unless `include_values=true`. nullable: true version: type: integer minimum: 1 description: >- Increments on every write. Send it as `If-Match` to make a write conditional. expires_at: type: string format: date-time description: ISO 8601 timestamp when the entry expires. created_at: type: string format: date-time description: ISO 8601 timestamp when the entry was first written. updated_at: type: string format: date-time description: ISO 8601 timestamp of the latest write or TTL refresh. written_by: $ref: '#/components/schemas/KvWriter' required: - key - version - expires_at - created_at - updated_at - written_by KvWriter: oneOf: - type: object properties: kind: type: string enum: - user id: type: string minLength: 1 description: User ID. required: - kind - id - type: object properties: kind: type: string enum: - chat_session id: type: string minLength: 1 description: Chat session ID. required: - kind - id - type: object properties: kind: type: string enum: - test_run id: type: string minLength: 1 description: Test run ID. required: - kind - id - type: object properties: kind: type: string enum: - api_key id: type: string minLength: 1 description: Project API key ID. required: - kind - id - type: object properties: kind: type: string enum: - system id: type: string nullable: true minLength: 1 description: Service name, when known. required: - kind - id description: Who last wrote or refreshed the entry. securitySchemes: Bearer: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.