---
title: "Read all item records for an item"
method: GET
path: "/projects/{projectId}/items/{itemId}/records"
tags: ["Items"]
---

# Read all item records for an item

`GET /projects/{projectId}/items/{itemId}/records`

## Request

- Base URL: `https://app.ketryx.com/api/v1`
- URL: `https://app.ketryx.com/api/v1/projects/{projectId}/items/{itemId}/records`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/ketryx/apis/ketryx-api/docs/projects/:projectId/items/:itemId/records/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns all records for a specific item, including built-in and custom fields. This is also the revision history of an EDMS document — a document ID is an item ID.

## Path parameters

- `projectId` string, required: Ketryx ID of the project, e.g., `KXPRJ12345`
- `itemId` string, required: Ketryx ID of the item, e.g., `KXITM12345`

## Query parameters

- `startAt` integer: Index to start at. Defaults to 0.
- `maxResults` integer: Maximum number of results to return
- `fields` string[]: Optional comma-separated list of additional fields to include in the response: approvalState, authors, versions

## Response `200`

Successful response

- object
  - `startAt` integer, required: Index that the pagination started at
  - `maxResults` integer, required: Maximum number of results returned
  - `records` object[], required: List of records
    - `id` string, required: Ketryx ID of this item record
    - `itemId` string, required: Ketryx ID of the item this record belongs to
    - `type` string, required: Item type by its user-facing label (taking into account potentially renamed item types)
    - `title` string, required: Title of this record
    - `state` 'OPEN' | 'IN_PROGRESS' | 'REOPENED' | 'RESOLVED' | 'CLOSED', nullable, required: Normalized workflow state of this record (OPEN, IN_PROGRESS, REOPENED, RESOLVED, or CLOSED)
    - `statusName` string, nullable, required: User-facing status name. Usually derived from state, but may be a custom Jira workflow status
    - `isControlled` boolean, required: Whether this is a controlled record
    - `isExternalApproval` boolean, required: Whether this record has external approval
    - `revision` integer, nullable, required: Revision number of this record (unique among all records of the same item)
    - `createdAt` string, date-time, required: Record creation date and time
    - `reporter` object, nullable, required: User who reported this record (the reporter of items synced from an external system, e.g. the Jira reporter). Null when the record has no reporter — Ketryx-created records track their creator in the authors field instead.
      - `id` string, nullable, required: Ketryx ID of the user, e.g., `KXUSR12345`
      - `name` string, required: Display name of the user
      - `email` string, nullable, required: Email address of the user, or null if not available (e.g. external Jira user with no Ketryx account)
    - `assignee` object, nullable, required: User currently responsible for this record. Named to match the POST item API and GraphQL; the Ketryx UI labels the same concept "Owner".
      - `id` string, nullable, required: Ketryx ID of the user, e.g., `KXUSR12345`
      - `name` string, required: Display name of the user
      - `email` string, nullable, required: Email address of the user, or null if not available (e.g. external Jira user with no Ketryx account)
    - `authors` object[], nullable, required: Ketryx users who have contributed edits to this record (derived from the changelog, falling back to reporter/creator). Only included when the fields query parameter contains "authors"; null otherwise.
      - `id` string, nullable, required: Ketryx ID of the user, e.g., `KXUSR12345`
      - `name` string, required: Display name of the user
      - `email` string, nullable, required: Email address of the user, or null if not available (e.g. external Jira user with no Ketryx account)
    - `introducedInVersion` object, nullable, required: Version this record was introduced in
      - `id` string, required: Ketryx ID of this version
      - `name` string, required: Full name
      - `versionNumber` string, nullable, required: Normalized version number derived from the version (its explicit version number, or extracted from the name), or null if it has none yet (e.g. a scoped version whose change request hasn't merged)
    - `obsoleteInVersion` object, nullable, required: Version this record was obsoleted in
      - `id` string, required: Ketryx ID of this version
      - `name` string, required: Full name
      - `versionNumber` string, nullable, required: Normalized version number derived from the version (its explicit version number, or extracted from the name), or null if it has none yet (e.g. a scoped version whose change request hasn't merged)
    - `versions` object[], nullable, required: Versions of the project (released or unreleased) in which this record is the record that applies to the item — the latest revision in the record's version range, unless another revision is locked to the version. Only included when the fields query parameter contains "versions"; null otherwise.
      - `id` string, required: Ketryx ID of this version
      - `name` string, required: Full name
      - `versionNumber` string, nullable, required: Normalized version number derived from the version (its explicit version number, or extracted from the name), or null if it has none yet (e.g. a scoped version whose change request hasn't merged)
    - `fields` object[], required: Fields and values for this record. Includes built-in system fields, organization-defined custom fields (customFieldsConfiguration), and project-level legacy extra fields (projectItemConfiguration.extraFieldNames). Custom and legacy entries are marked with isCustom = true.
      - `label` string, required: Human-readable label of the field
      - `type` 'string' | 'jdf' | 'select' | 'multiselect' | 'date' | 'number', required: Type of field value
      - `value` unknown, required
      - `isCustom` boolean, required: True for custom fields — either organization-defined (customFieldsConfiguration) or project-level legacy (extraFieldNames). False for built-in system fields.
    - `relations` object[], required: Relation to other items from this record
      - `type` string, required: Relation type name (e.g. "fulfills"). Every custom relation reports "custom" here regardless of its configured name — see typeName for that, and match on this value to detect a custom relation.
      - `typeName` string, required: Human-readable relation name, and the value the POST item API accepts: the configured relationName for a custom relation (e.g. "uses"), otherwise the same name as type.
      - `typeKey` string, required: Stable key identifying the relation type. For system relations this is the enum value (e.g. "FULFILLS"); for custom relations this is the customTypeId (e.g. "SW_USES_HW").
      - `toItem` object, required
        - `id` string, required
        - `projectId` string, required
    - `fileUrl` string, nullable, required: URL of the file associated with this record (if any). This can be used to download the underlying file of a document record.
    - `approvalState` object, nullable, required: Approval state of this record.
      - `steps` object[], required: Approval steps for this record
        - `name` string, required: Name of the approval step
        - `type` 'group' | 'user', required: Type of approval step. "group" indicates approval is assigned to a group of users, "user" indicates approval is assigned to a specific individual user.
        - `group` object: Group assigned to this approval step. Present only when type is "group". If undefined, this is a user-based approval step.
          - `id` string, required: ID of the approval group
          - `name` string, required: Name of the approval group
        - `users` object[]: All users associated with this approval step. For group-based steps: includes all users from the group and any nested groups. For user-based steps: contains the single assigned user. Always present when there are users to notify.
          - `id` string, required: ID of the user who approved
          - `email` string: Email of the user who approved
        - `approvingUsers` object[], required: Users who have actually provided approval for this step
          - `id` string, required: ID of the user who approved
          - `email` string: Email of the user who approved
        - `isFullyApproved` boolean, required: Whether this step has received all required approvals
        - `minApprovals` number, required: Minimum number of approvals required to complete this step
      - `designInputsBlockingApproval` object[]: Design inputs blocking approval of this record
        - `id` string, required: ID of the blocking item
        - `projectId` string, required: Project ID of the blocking item
      - `instructionText` string: Instruction text for the approval process
      - `invalidFields` string[]: Fields that are invalid and blocking approval
      - `milestoneBlockingApproval` object: Milestones blocking approval of this record
        - `id` string, required: ID of the blocking milestone
        - `name` string, required: Name of the blocking milestone

## Other responses

- `400`: Invalid input data
- `401`: Authorization not provided
- `403`: Insufficient access
- `404`: Not found
- `500`: Internal server error

---

[API](https://skmtc.dev/ketryx/apis/ketryx-api.md) - [All operations](https://skmtc.dev/ketryx/apis/ketryx-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ketryx/apis/ketryx-api/revisions/a2a484dc35ca?raw)