---
title: "GetContainerList"
slug: "getcontainerlist"
updated: 2026-10-22T10:47:58Z
published: 2026-10-22T10:47:58Z
canonical: "api-gov.ncloud-docs.com/getcontainerlist"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://api-gov.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GetContainerList

Classic/VPC 환경에서 이용 가능합니다.

컨테이너(버킷)의 목록을 조회합니다.

          참고

          

Subaccount의 경우, Subaccount 전용 External API Gateway를 통해 사용할 수 있습니다. 자세한 내용은 SubAccount의 [GetContainerList](/docs/getcontainerlist-subaccount) API를 참조해 주십시오.

## 요청

요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.

| 메서드 | URI |
| --- | --- |
| GET | /v1/AUTH_{project_id} |

### 요청 헤더

헤더에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `X-Auth-Token` | String | Required | 발급한 토큰(Token) 값 |
| `Accept` | String | Optional | 호출 결과의 포맷 지정 - `application/json` \|`application/xml` \|`text/xml` |

### 요청 경로 파라미터

파라미터에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `project_id` | String | Required | 프로젝트 ID - 프로젝트 ID 확인 방법은 [Archive Storage 개요](/docs/storage-archivestorage#%EC%9D%B8%EC%A6%9D) 참조 |
| `container` | String | Required | 조회할 컨테이너(버킷) 이름 |

### 요청 쿼리 파라미터

파라미터에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `limit` | Integer | Optional | 호출 결과의 최대 개수 제한 - 0~10,000 (기본값: 10,000) |
| `marker` | String | Optional | 특정 컨테이너(버킷) 이후 목록을 반환 |
| `end_marker` | String | Optional | 특정 컨테이너(버킷) 이전 목록을 반환 |
| `prefix` | String | Optional | 해당 문자열로 시작하는 컨테이너(버킷) 목록 반환 |
| `reverse` | String | Optional | 컨테이너의 이름으로 정렬하여 목록을 출력 - 기본값: `false` (descending) |

### 요청 예시

요청 예시는 다음과 같습니다.

#### format 쿼리 파라미터 없이 요청

`format` 쿼리 파라미터 없이 요청하는 예시는 다음과 같습니다.

```
curl -X GET "https://kr.archive.gov-ncloudstorage.com/v1/AUTH_{project_id}" 
-H "X-Auth-Token: $token"
```

#### format 쿼리 파라미터를 JSON으로 요청

`format` 쿼리 파라미터를 JSON으로 요청하는 예시는 다음과 같습니다.

```
curl -X GET "https://kr.archive.gov-ncloudstorage.com/v1/AUTH_{project_id}?format=json" 
-H "X-Auth-Token: $token"
```

#### format 쿼리 파라미터를 XML로 요청

`format` 쿼리 파라미터를 XML로 요청하는 예시는 다음과 같습니다.

```
curl -X GET "https://kr.archive.gov-ncloudstorage.com/v1/AUTH_{project_id}?format=xml" 
-H "X-Auth-Token: $token"
```

## 응답

응답 형식을 설명합니다.

### 응답 헤더

헤더에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `Content-Type` | String | - | 응답 결과의 MIME 타입 |
| `X-Account-Container-Count` | Integer | - | 해당 어카운트에 있는 전체 컨테이너(버킷) 개수 |
| `X-Account-Object-Count` | Integer | - | 해당 어카운트의 전체 오브젝트 개수 |
| `X-Account-Bytes-Used` | Integer | - | 해당 어카운트가 사용하는 전체 용량 크기(Byte) |
| `X-Timestamp` | Integer | - | 컨테이너(버킷)가 생성된 시각(Unix Timestamp) |
| `X-Account-Storage-Policy-name-Bytes-Used` | Integer | - | 헤더명의 `name`에 해당하는 storage policy의 전체 용량 크기(Byte) |
| `X-Account-Storage-Policy-name-Container-Count` | Integer | - | 헤더명의 `name`에 해당하는 storage policy의 전체 컨테이너(버킷) 개수 |
| `X-Account-Storage-Policy-name-Object-Count` | Integer | - | 헤더명의 `name`에 해당하는 storage policy의 전체 오브젝트 개수 |
| `X-Account-Meta-name` | String | - | 어카운트의 메타데이터 - 헤더명의 `name` 부분이 메타데이터의 키 역할을 함 |
| `X-Account-Meta-Temp-URL-Key` | String | - | temporary URL을 위한 Secret Key 값 |
| `X-Account-Meta-Temp-URL-Key-2` | String | - | temporary URL을 위한 두 번째 Secret Key 값 |
| `Accept-Ranges` | String | - | 해당 컨테이너(버킷)가 허용하는 Range 타입 |
| `Content-Length` | String | - | 응답 결과의 길이(Byte) |
| `x-account-project-domain-id` | String | - | API 이용 시 필요한 Domain ID |
| `X-Trans-Id` | String | - | 해당 요청의 트랜잭션 ID |
| `X-Openstack-Request-Id` | String | - | 해당 요청의 트랜잭션 ID - X-Trans-Id와 동일 |
| `Date` | String | - | 해당 요청의 응답 시간(UTC) |

### 응답 구문

응답 구문은 다음과 같습니다.

format 쿼리 파라미터 없이 요청한 경우에는 컨테이너(버킷)에 속한 오브젝트의 이름만 plain 텍스트 포맷으로 응답합니다.

```
"string"
```

```
[
   {
      "count": "number",
      "last_modified":"string",
      "bytes":"number",
      "name":"string"
   }
]
```

```
<?xml version="1.0" encoding="UTF-8"?>
<account name="AUTH_5942771066a0482bb6aaf7f5bc792b00">
   <container>
      <name>"string"</name>
      <count>"number"</count>
      <bytes>"number"</bytes>
      <last_modified>"string"</last_modified>
   </container>
</account>
```

### 응답 바디

응답 바디에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `name` | String | - | 해당 컨테이너의 이름 |
| `count` | Integer | - | 해당 컨테이너에 있는 오브젝트 개수 |
| `bytes` | Integer | - | 해당 컨테이너에 있는 전체 오브젝트의 크기(Byte) |
| `last_modified` | String | - | 최종 수정 일시 |

### 응답 상태 코드

응답 상태 코드에 대한 설명은 다음과 같습니다.

| HTTP 상태 코드 | 코드 | 메시지 | 설명 |
| --- | --- | --- | --- |
| 200 | - | OK | 요청 성공 |
| 204 | - | No Content | Content-Type이 `plain`이고, 요청에 해당되는 내용이 없는 경우 발생 |
| 403 | - | Not Found | 컨테이너(버킷)이 존재하지 않는 경우 발생 |

### 응답 예시

응답 예시는 다음과 같습니다.

#### format 쿼리 파라미터 없이 요청한 경우의 응답

`format` 쿼리 파라미터 없이 요청했을 때의 응답 예시는 다음과 같습니다.

```
HTTP/1.1 200 OK
Content-Length: 38
Accept-Ranges: bytes
X-Timestamp: 1535685069.28154
X-Account-Bytes-Used: 0
X-Account-Container-Count: 2
Content-Type: text/plain; charset=utf-8
X-Account-Object-Count: 0
x-account-project-domain-id: default
X-Trans-Id: tx928992622dd248ee9b3e8-005b972569
X-Openstack-Request-Id: tx928992622dd248ee9b3e8-005b972569
Date: Tue, 11 Sep 2018 02:16:09 GMT
```

```
ncloud-container-0
ncloud-container-1
```

#### format 쿼리 파라미터를 JSON으로 요청한 경우의 응답

`format` 쿼리 파라미터를 JSON으로 요청했을 때의 응답 예시는 다음과 같습니다.

```
HTTP/1.1 200 OK
Content-Length: 96
X-Account-Object-Count: 1
X-Timestamp: 1389453423.35964
X-Account-Meta-Subject: Literature
X-Account-Bytes-Used: 14
X-Account-Container-Count: 2
Content-Type: application/json; charset=utf-8
Accept-Ranges: bytes
X-Trans-Id: tx274a77a8975c4a66aeb24-0052d95365
X-Openstack-Request-Id: tx274a77a8975c4a66aeb24-0052d95365
Date: Fri, 17 Jan 2014 15:59:33 GMT
```

```
[
    {
        "count": 0,
        "bytes": 0,
        "name": "janeausten",
        "last_modified": "2013-11-19T20:08:13.283452"
    },
    {
        "count": 1,
        "bytes": 14,
        "name": "marktwain",
        "last_modified": "2016-04-29T16:23:50.460230"
    }
]
```

#### format 쿼리 파라미터를 XML로 요청한 경우의 응답

`format` 쿼리 파라미터를 XML로 요청했을 때의 응답 예시는 다음과 같습니다.

```
HTTP/1.1 200 OK
Content-Length: 262
X-Account-Object-Count: 1
X-Timestamp: 1389453423.35964
X-Account-Meta-Subject: Literature
X-Account-Bytes-Used: 14
X-Account-Container-Count: 2
Content-Type: application/xml; charset=utf-8
Accept-Ranges: bytes
X-Trans-Id: tx69f60bc9f7634a01988e6-0052d9544b
X-Openstack-Request-Id: tx69f60bc9f7634a01988e6-0052d9544b
Date: Fri, 17 Jan 2014 16:03:23 GMT
```

```
<?xml version="1.0" encoding="UTF-8"?>
<account name="my_account">
    <container>
        <name>janeausten</name>
        <count>0</count>
        <bytes>0</bytes>
        <last_modified>2013-11-19T20:08:13.283452</last_modified>
    </container>
    <container>
        <name>marktwain</name>
        <count>1</count>
        <bytes>14</bytes>
        <last_modified>2016-04-29T16:23:50.460230</last_modified>
    </container>
</account>
```