> ## Documentation Index
> Fetch the complete documentation index at: https://developers.bottari.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 행 쿼리하기

> 데이터베이스의 행을 필터와 정렬로 읽습니다.

행 목록을 읽습니다. 기본으로 휴지통 행과 보관한 행은 빠집니다. 정렬을 지정하지 않으면 최근에 만든 행부터 반환합니다.

이 엔드포인트는 호출 횟수를 따로 제한합니다. 연동마다 초당 약 3회입니다. [호출 횟수 제한 자세히 알아보기 →](https://developers.bottari.ai/ko/limits/rate-limits.md)

**Authorization** `string` *required*

`Bearer <토큰>` 형식입니다. [토큰 자세히 알아보기 →](https://developers.bottari.ai/ko/auth/tokens.md)

**Bottari-Version** `string`

선택 항목입니다. `2026-03-11`만 받습니다. 빼면 현재 버전을 사용하고, 다른 값을 보내면 400을 반환합니다.

**id** `string` *required*

데이터 소스 ID입니다. 데이터베이스 ID를 넣으세요.

**filter\_properties** `string[]`

응답에 담을 속성 이름이나 ID입니다. 없는 속성은 400을 반환합니다.

**filter** `object`

[필터와 정렬 자세히 알아보기 →](https://developers.bottari.ai/ko/api-reference/filters.md)

**sorts** `object[]`

[정렬 자세히 알아보기 →](https://developers.bottari.ai/ko/api-reference/filters.md#정렬)

**start\_cursor** `string`

앞 응답의 `next_cursor`입니다. [전부 읽기 자세히 알아보기 →](#전부-읽기)

**page\_size** `number` (default: 100)

1\~100입니다.

**in\_trash** `boolean`

`true`면 휴지통에 있고 보관하지 않은 행을 반환합니다.

**is\_archived** `boolean`

`true`면 보관했고 휴지통에 없는 행을 반환합니다. `in_trash`와 `is_archived`가 모두 `true`면 휴지통에 있으면서 보관한 행을 반환합니다.

**result\_type** `string`

`page`만 받습니다.

**results** `object[]`

`page` 객체 목록입니다. [속성 값 자세히 알아보기 →](https://developers.bottari.ai/ko/api-reference/property-values.md)

**next\_cursor** `string | null`

다음 목록의 커서입니다.

**has\_more** `boolean`

더 있으면 `true`입니다.

**type** `string`

항상 `page_or_data_source`입니다.

## 전부 읽기

쿼리 결과의 전체 행 수에는 상한이 없습니다. `has_more`가 `true`면 `next_cursor`를 `start_cursor`로 보내고, `has_more`가 `false`가 될 때까지 반복하세요.

페이지마다 같은 `filter` · `sorts` · `in_trash` · `is_archived`를 키 순서까지 같게 보내세요. `start_cursor`와 `page_size`만 바꿀 수 있습니다. 다르면 커서가 400을 반환합니다.

```bash theme={null}
curl https://api.bottari.ai/v1/data_sources/exampleDb001/query \
  -X POST \
  -H "Authorization: Bearer $BOTTARI_TOKEN" \
  -H "Bottari-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "property": "담당 팀", "select": { "equals": "운영" } },
    "sorts": [{ "timestamp": "created_time", "direction": "descending" }],
    "start_cursor": "eyJxIjoiZXhhbXBsZSJ9"
  }'
```

## 오류

| 상태 | `code` | 원인 |
| - | - | - |
| 400 | `validation_error` | 없는 본문 키, 틀린 필터나 정렬, 같은 `filter` · `sorts` · `in_trash` · `is_archived` 없이 보낸 커서, 없는 `filter_properties`입니다. |
| 404 | `object_not_found` | 없거나 연결하지 않았거나 휴지통에 있는 데이터베이스입니다. |
| 429 | `rate_limited` | 호출 횟수를 넘겼습니다. |

공통 오류는 [공통 규칙](https://developers.bottari.ai/ko/api-reference/overview.md#오류)에서 확인할 수 있습니다.

```bash curl theme={null}
curl "https://api.bottari.ai/v1/data_sources/exampleDb001/query?filter_properties=title&filter_properties=exampleFld01" \
  -X POST \
  -H "Authorization: Bearer $BOTTARI_TOKEN" \
  -H "Bottari-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "property": "담당 팀",
      "select": {
        "equals": "운영"
      }
    },
    "sorts": [
      {
        "timestamp": "created_time",
        "direction": "descending"
      }
    ],
    "page_size": 10
  }'
```

```json 200 theme={null}
{
  "object": "list",
  "results": [
    {
      "object": "page",
      "id": "exampleRow01",
      "created_time": "2026-01-15T02:30:00.000Z",
      "last_edited_time": "2026-01-15T03:10:00.000Z",
      "created_by": {
        "object": "user",
        "id": "11111111-1111-4111-8111-111111111111"
      },
      "last_edited_by": {
        "object": "user",
        "id": "11111111-1111-4111-8111-111111111111"
      },
      "in_trash": false,
      "cover": null,
      "icon": null,
      "parent": {
        "type": "data_source_id",
        "data_source_id": "exampleDb001",
        "database_id": "exampleDb001"
      },
      "is_archived": false,
      "is_locked": false,
      "properties": {
        "이름": {
          "id": "title",
          "type": "title",
          "title": [
            {
              "type": "text",
              "text": {
                "content": "1월 주문 확인",
                "link": null
              },
              "annotations": {
                "bold": false,
                "italic": false,
                "strikethrough": false,
                "underline": false,
                "code": false,
                "color": "default"
              },
              "plain_text": "1월 주문 확인",
              "href": null
            }
          ]
        },
        "담당 팀": {
          "id": "exampleFld01",
          "type": "select",
          "select": {
            "id": "exampleOpt01",
            "name": "운영",
            "color": "blue"
          }
        }
      },
      "url": "https://app.bottari.ai/t/exampleTeam1/p/exampleRow01",
      "public_url": null
    }
  ],
  "next_cursor": "eyJxIjoiZXhhbXBsZSJ9",
  "has_more": true,
  "type": "page_or_data_source",
  "page_or_data_source": {},
  "request_id": "33333333-3333-4333-8333-333333333333"
}
```

```json 400 theme={null}
{
  "object": "error",
  "status": 400,
  "code": "validation_error",
  "message": "body failed validation: body.start_cursor should be a valid cursor for this query.",
  "request_id": "33333333-3333-4333-8333-333333333333"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.