> For the complete documentation index, see [llms.txt](https://api-kit.prix.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-kit.prix.im/platform/search-custom-table-rows.md).

# 커스텀테이블 행 목록 조회 API

커스텀테이블의 행 데이터를 조회할 수 있는 API를 제공합니다.

커스텀테이블의 행 데이터를 조회할 수 있는 API입니다.

* 테이블은 프릭스 어드민에서 설정한 `slug` 또는 테이블 `uuid`로 식별합니다.
* 행은 API 권한이 연결된 멤버가 속한 팀의 조회 권한 범위로 반환됩니다.
* 셀 값(`columnItems[].value`)은 컬럼 타입에 따라 아래 형식으로 제공됩니다.

| 컬럼 타입    | value 형식                                                            |
| -------- | ------------------------------------------------------------------- |
| STRING   | 문자열                                                                 |
| NUMBER   | 숫자                                                                  |
| BOOLEAN  | true / false                                                        |
| DATE     | ISO 8601 날짜 문자열                                                     |
| TAG      | `[{ "id": 5, "name": "자문" }]` 형태의 배열                                |
| RELATION | 대상이 커스텀테이블이면 `[{ "uuid", "title" }]`, 고객이면 `[{ "id", "title" }]` 배열 |
| LOOKUP   | 문자열 (참조한 값의 표시 문구)                                                  |

<br>

## `GET` kit-api/v1/custom-tables/{key}/rows

Method: GET\
Endpoint: kit-api/v1/custom-tables/{key}/rows

* `key`에는 테이블 `slug` 또는 `uuid`를 사용할 수 있습니다.

<br>

## Example

```
...kit-api/v1/custom-tables/timesheet/rows?limit=100&updatedAtAfter=2026-08-01T00:00:00.000Z
```

```
...kit-api/v1/custom-tables/706a317d-5fbb-4870-930b-eade57f4f955/rows?slugColumnKeys=work-type&slugColumnValues=자문
```

<br>

## Request Query

| Key              | Description                                         | Required |
| ---------------- | --------------------------------------------------- | -------- |
| limit            | 목록 개수 (default 10, max 100)                         | no       |
| offset           | 스킵할 목록 개수                                           | no       |
| title            | 행 제목으로 조회 (부분 일치)                                   | no       |
| dealUuids        | 해당 uuid 속성을 가진 프로젝트들과 연결된 행 조회 (콤마 구분)              | no       |
| customerIds      | 해당 id 속성을 가진 고객들과 연결된 행 조회 (콤마 구분)                  | no       |
| createdAtAfter   | 해당 날짜 이후 생성된 행 조회 (date)                            | no       |
| createdAtBefore  | 해당 날짜 이전 생성된 행 조회 (date)                            | no       |
| updatedAtAfter   | 해당 날짜 이후 변경된 행 조회 (date, 증분 동기화용)                   | no       |
| updatedAtBefore  | 해당 날짜 이전 변경된 행 조회 (date)                            | no       |
| slugColumnKeys   | 검색할 컬럼의 slug 목록 (콤마 구분)                             | no       |
| slugColumnValues | 검색할 컬럼별 값 목록 (콤마 구분). slugColumnKeys가 있으면 필수, 개수 일치 | no       |

<br>

## Response

* 목록은 생성일 내림차순으로 정렬됩니다.
* `users`, `customers`, `deals`는 테이블 설정(option)에서 사용하는 항목만 값이 채워지고, 사용하지 않는 항목은 빈 배열입니다.
* 히스토리 기능을 사용하는 테이블은 현재 값만 반환됩니다.

```json
{
  "ok": true, // api 성공
  "data": {
    "total": 1,
    "rows": [
      {
        "id": 501,
        "uuid": "c1f3a2d4-1b2c-4d5e-8f90-123456789abc", // 행 식별값
        "title": "2026-08-01 홍길동", // 행 제목
        "users": [{ "id": 3, "name": "홍길동" }], // 담당자
        "customers": [], // 고객
        "deals": [{ "uuid": "38432ad8-a21f-43b3-9912-44295e3ecca1", "name": "A사 법률 자문", "customKey": "P-2026-001" }], // 프로젝트
        "columnItems": [
          // 셀 값. columnId는 커스텀테이블 목록 조회 API의 columns[].id (컬럼 타입별 value 형식은 상단 표 참고)
          { "columnId": 101, "name": "근무일", "slug": "work-date", "value": "2026-08-01T00:00:00.000Z" },
          { "columnId": 102, "name": "업무 구분", "slug": "work-type", "value": [{ "id": 5, "name": "자문" }] },
          { "columnId": 103, "name": "시간(분)", "slug": "minutes", "value": 90 },
          { "columnId": 104, "name": "관련 안건", "slug": "matter", "value": [{ "uuid": "a3c1...", "title": "A사 계약검토" }] },
          { "columnId": 105, "name": "안건 담당자", "slug": "matter-owner", "value": "김변호사" }
        ],
        "createdBy": { "id": 3, "name": "홍길동" }, // 생성자 (없으면 null)
        "createdAt": "2026-08-01T09:00:00.000Z", // 생성일
        "updatedAt": "2026-08-01T09:00:00.000Z" // 변경일
      }
    ]
  }
}
```

<br>

```json
{
  "ok": false, // api 실패
  "message": "error message", // Error가 존재하면 message(string)로 전달
  "errorCode": "ERROR_CODE"
}
```

<br>

## Error Codes

| Status Code | Error Code                                | Description                                     |
| ----------- | ----------------------------------------- | ----------------------------------------------- |
| 400         | SLUG\_COLUMN\_KEYS\_AND\_VALUES\_MISMATCH | slugColumnKeys 값과 slugColumnValues 값의 개수가 다른 경우 |
| 403         | CUSTOM\_TABLE\_ACCESS\_DENIED             | 연결된 멤버에게 테이블 조회 권한이 없는 경우                       |
| 404         | NOT\_FOUND\_CUSTOM\_TABLE                 | slug 또는 uuid에 해당하는 테이블이 없는 경우                   |
| 404         | NOT\_FOUND\_CUSTOM\_COLUMN                | slugColumnKeys에 존재하지 않는 컬럼 slug가 포함된 경우         |

<br>