---
title: API로 데이터 가져오기
description: 대규모 데이터 가져오기에 Twenty의 API를 언제, 어떻게 사용할지 안내합니다.
---

## 개요

Twenty는 프로그램 방식의 데이터 가져오기를 위해 **GraphQL** 및 **REST API**를 모두 제공합니다. 데이터 규모상 CSV 가져오기가 실용적이지 않거나 자동화된 반복 가져오기가 필요한 경우 API를 사용하세요.

## API 가져오기 사용 시기

| 시나리오                 | 권장 방법            |
| -------------------- | ---------------- |
| 10,000개 미만의 레코드      | CSV 가져오기         |
| 10,000 - 50,000개 레코드 | CSV 가져오기(파일로 분할) |
| **50,000개 이상의 레코드**  | **API 가져오기**     |
| 1회성 마이그레이션           | 둘 다 가능(규모에 따라)   |
| **반복 가져오기**          | **API 가져오기**     |
| **실시간 동기화**          | **API 가져오기**     |
| **다른 시스템과의 통합**      | **API 가져오기**     |

<Note>수십만 건 규모의 데이터셋의 경우, API가 여러 번의 CSV 가져오기보다 훨씬 빠르고 더 신뢰할 수 있습니다.</Note>

## API 속도 제한

시스템 안정성을 보장하기 위해 Twenty는 속도 제한을 적용합니다:

| 제한               | 값            |
| ---------------- | ------------ |
| **분당 요청 수**      | 100          |
| **배치 호출당 레코드 수** | 60           |
| **최대 처리량**       | ~6,000 레코드/분 |

<Warning>
**이 한도를 기준으로 가져오기 계획을 수립하세요.**

최대 처리량 기준으로 100,000개 레코드를 가져오는 데 약 17분이 소요됩니다. 오류 처리와 재시도를 위한 여유 시간을 추가하세요.
</Warning>

## 시작하기

### 1단계: API 키 받기

1. **설정 → 개발자**로 이동하세요.
2. **+ API 키 생성**을 클릭하세요.
3. 키에 설명적인 이름을 지정하세요.
4. API 키를 즉시 복사하세요(다시 표시되지 않습니다).
5. 안전하게 보관하세요.

<Warning>
**API 키를 비공개로 유지하세요.**

API 키를 가진 누구나 워크스페이스 데이터에 접근하고 수정할 수 있습니다. 코드 저장소에 커밋하거나 공개적으로 공유하지 마세요.
</Warning>

### 2단계: 사용할 API 선택

Twenty는 두 가지 유형의 API를 지원합니다:

| API         | 적합한 용도                        | 문서                               |
| ----------- | ----------------------------- | -------------------------------- |
| **GraphQL** | 유연한 쿼리, 연관 데이터 조회, 복잡한 작업에 적합 | [API 문서](/l/ko/developers/extend/api) |
| **REST**    | 단순한 CRUD 작업, 익숙한 REST 패턴      | [API 문서](/l/ko/developers/extend/api) |

두 API 모두 다음을 지원합니다:

* 레코드 생성, 조회, 업데이트 및 삭제
* **배치 작업** — 호출당 최대 60개 레코드를 생성하거나 업데이트

**가져오기에서는 배치 작업을 사용**하여 한도 내에서 처리량을 극대화하세요.

### 3단계: 가져오기 순서 계획

CSV 가져오기와 마찬가지로, 관계형 데이터에서는 **순서가 중요**합니다:

1. **회사** 먼저(종속성 없음)
2. 그다음 **사람**(회사에 연결 가능)
3. 세 번째로 **기회**(회사 및 사람에 연결 가능)
4. **작업/노트**(위 항목 중 어느 것에도 연결 가능)
5. **사용자 지정 객체**(종속성을 따름)

## 모범 사례

### 요청 일괄 처리

* 레코드를 한 번에 하나씩 보내지 마세요
* API 호출당 최대 **60개 레코드**로 묶으세요
* 이렇게 하면 한도 내에서 처리량을 극대화할 수 있습니다

### 속도 제한 처리

* 요청 사이에 지연을 구현하세요(지속적인 가져오기의 경우 최소 600ms)
* 한도에 도달하면 지수 백오프를 사용하세요
* 429(Too Many Requests) 응답을 모니터링하세요

### 먼저 데이터 검증

* 가져오기 전에 데이터를 정리하고 검증하세요
* 필수 필드가 채워졌는지 확인하세요
* 형식이 Twenty의 요구 사항과 일치하는지 확인하세요([필드 매핑](/l/ko/user-guide/data-migration/capabilities/field-mapping) 참조)

### 모든 항목 로깅

* 가져온 모든 레코드를 로깅하세요(ID 포함)
* 전체 컨텍스트와 함께 오류를 로깅하세요
* 이는 문제를 디버깅하고 완료 여부를 확인하는 데 도움이 됩니다

### 먼저 테스트

* 소량 배치(10-20개 레코드)로 테스트하세요
* 데이터가 Twenty에 올바르게 표시되는지 확인하세요
* 그런 다음 전체 가져오기를 실행하세요

### 중복 방지를 위한 업서트

GraphQL API는 **배치 업서트**를 지원합니다 — 레코드가 있으면 업데이트하고, 없으면 생성합니다. 이렇게 하면 가져오기를 다시 실행할 때 중복을 방지할 수 있습니다.

## 객체 및 필드 이름 찾기

사용 가능한 객체와 필드를 확인하려면:

1. **설정 → API 및 웹훅**으로 이동하세요
2. **Metadata API**를 살펴보세요
3. 모든 표준 및 사용자 지정 객체와 해당 필드를 확인하세요

문서에는 모든 표준 및 사용자 지정 객체, 해당 필드, 예상 데이터 유형이 표시됩니다.

## 전문 서비스

복잡한 API 마이그레이션의 경우, 파트너가 도와드립니다:

| 서비스             | 포함 내용              |
| --------------- | ------------------ |
| **데이터 모델 설계**   | 최적의 데이터 구조를 설계     |
| **마이그레이션 스크립트** | 가져오기 스크립트를 작성하고 실행 |
| **데이터 변환**      | 복잡한 매핑과 정리를 수행     |
| **검증 및 QA**     | 마이그레이션이 완료되었는지 확인  |

**적합한 용도:**

* 100,000개 이상의 레코드 마이그레이션
* 복잡한 데이터 변환
* 빠듯한 일정
* 개발 리소스가 없는 팀

[contact@twenty.com](mailto:contact@twenty.com)으로 문의하시거나 당사의 [구현 서비스](/l/ko/user-guide/getting-started/capabilities/implementation-services)를 확인하세요.

## FAQ

<AccordionGroup>
  <Accordion title="GraphQL과 REST의 차이는 무엇인가요?">
    GraphQL은 단일 쿼리로 필요한 데이터만 정확히 요청할 수 있으며, 복잡한 작업에 더 적합합니다. REST는 표준 HTTP 메서드(GET, POST, PUT, DELETE)를 사용하며, 기존 API로 작업해 본 경험이 있다면 더 익숙할 수 있습니다.
  </Accordion>

  <Accordion title="API를 통해 기존 레코드를 업데이트할 수 있나요?">
    예! 레코드의 `id`와 함께 업데이트 뮤테이션(GraphQL) 또는 PUT/PATCH 요청(REST)을 사용하세요.
  </Accordion>

  <Accordion title="중복은 어떻게 처리하나요?">
    고유 식별자(이메일, 도메인)를 사용해 먼저 기존 레코드를 조회하세요. 존재하면 업데이트하고, 없으면 생성하세요.
  </Accordion>

  <Accordion title="API를 통해 레코드를 삭제할 수 있나요?">
    예, 삭제 뮤테이션(GraphQL) 또는 DELETE 요청(REST)을 사용하세요.
  </Accordion>

  <Accordion title="Python 또는 Node.js SDK가 있나요?">
    현재는 없습니다. 하지만 두 API는 어떤 언어의 HTTP 클라이언트와도 작동합니다.
  </Accordion>
</AccordionGroup>

## API 문서

전체 구현 세부정보, 코드 예제, 스키마 참조는 다음을 확인하세요:

* [API 문서](/l/ko/developers/extend/api)
