---
title: Get collection
description: Read a collection’s settings, readiness, and file counts.
doc_version: 0.1.0-preview
last_updated: 2026-09-14
---

# Get collection

`GET /namespaces/{namespace}/collections/{collection}`

Read a collection’s settings, readiness, and file counts.

**Permission:** Cluster key, or a scoped key with read (write includes read).

[API key types and authentication](/engine/reference/authentication.md).

Use status and file_counts to distinguish empty, processing, ready, and failed content.

A resource outside the key’s namespace or collection scope returns 404, even when that resource exists.

## Example request

```http
GET /namespaces/acme/collections/incident-logs HTTP/1.1
Host: engine.example.com
Authorization: Bearer <GRAPHON_ENGINE_API_KEY>
```

## Path parameters

### `namespace`

**string · required**

Namespace name or ns_ ID. It must be visible to this key.

### `collection`

**string · required**

Collection name or col_ ID within the namespace. It must be visible to this key.

## Responses

### 200 · Success

The requested resource or result.

Content type: `application/json`.

#### Response headers

##### `x-request-id`

**string · required**

Request correlation ID. Retain it when investigating a failed or unexpected request.

```json
{
  "id": "col_01K6Q6N7D8E9F0G1H2J3K4M5N6",
  "namespace": "acme",
  "name": "incident-logs",
  "display_name": "Incident logs",
  "status": "ready",
  "access_control": "off",
  "processing": {
    "keyword": true,
    "semantic": true,
    "graph": true
  },
  "index_generation": "gen_example",
  "file_counts": {
    "pending": 0,
    "indexing": 0,
    "ready": 1,
    "failed": 0
  },
  "created_at": "2026-10-06T10:00:00Z",
  "updated_at": "2026-10-06T10:00:00Z"
}
```

#### Response fields

##### `access_control`

**string · required**

Whether Search and Query apply access rules. off accepts no principals. enforced requires principals and starts with an empty root reader list.

- `off`: Retrieval uses the key’s scope and does not accept principals.
- `enforced`: Retrieval requires principals and applies the collection’s access rules.

##### `created_at`

**string (date-time) · required**

Time the resource was created, as an ISO 8601 UTC timestamp.

##### `display_name`

**string · required · nullable**

Human-readable label. This label does not change the resource name used in URLs.

##### `file_counts`

**object · required**

Current number of living files in each processing state.

###### `file_counts.failed`

**integer · required**

Files whose processing failed.

###### `file_counts.indexing`

**integer · required**

Files whose content is being indexed.

###### `file_counts.pending`

**integer · required**

Files accepted but waiting for bytes or processing.

###### `file_counts.ready`

**integer · required**

Files available to Search and Query.

##### `id`

**string · required**

Immutable collection ID with the col_ prefix.

##### `index_generation`

**string · required · nullable**

Opaque identifier for the searchable generation. It changes when indexed data changes. Null means that no searchable generation exists.

##### `name`

**string · required**

URL name. Use 1–63 lowercase letters, digits, underscores, or hyphens. Start with a letter or digit. A name cannot match its resource ID format.

##### `namespace`

**string · required**

Name of the namespace that contains this collection.

##### `processing`

**object · required**

Index features for this collection. Flags omitted on create default to true. Flags omitted on update keep their values. At least one flag must remain enabled.

###### `processing.graph`

**boolean · required**

Whether graph processing is enabled for this collection.

###### `processing.keyword`

**boolean · required**

Whether lexical Search is enabled for this collection.

###### `processing.semantic`

**boolean · required**

Whether meaning-based Search is enabled for this collection.

##### `status`

**string · required**

Aggregate readiness of the collection. A ready file permits retrieval. Check file_counts for failures or ongoing processing.

- `empty`: No living files. Search returns no results. Query returns collection_empty.
- `indexing`: Files are processing and none is ready yet.
- `ready`: At least one file is ready for retrieval.
- `degraded`: At least one file is ready and at least one failed.
- `failed`: Files exist but none is ready. Inspect file errors.
- `deleting`: Deletion is in progress. Retrieval returns not_found.

##### `updated_at`

**string (date-time) · required**

Time the resource last changed, as an ISO 8601 UTC timestamp.

## Errors

[Error format and retry guidance](/engine/reference/errors.md).

### 400 · `invalid_request`

A field, path, parameter, or conditional request rule is invalid.

Correct the request. Unknown fields are rejected.

```json
{
  "error": {
    "code": "invalid_request",
    "message": "A field, path, parameter, or conditional request rule is invalid.",
    "request_id": "req_example",
    "retryable": false,
    "details": {}
  }
}
```

### 401 · `unauthenticated`

The API key is missing, invalid, or revoked.

Send an active key in Authorization: Bearer or X-API-Key.

```json
{
  "error": {
    "code": "unauthenticated",
    "message": "The API key is missing, invalid, or revoked.",
    "request_id": "req_example",
    "retryable": false,
    "details": {}
  }
}
```

### 403 · `forbidden`

The key can see the resource but lacks permission for this operation.

Use a key with the required action or scope kind.

```json
{
  "error": {
    "code": "forbidden",
    "message": "The key can see the resource but lacks permission for this operation.",
    "request_id": "req_example",
    "retryable": false,
    "details": {}
  }
}
```

### 404 · `not_found`

The resource is absent, deleted, or outside this key’s scope.

Check the identifier and the key’s namespace and collection scope.

```json
{
  "error": {
    "code": "not_found",
    "message": "The resource is absent, deleted, or outside this key’s scope.",
    "request_id": "req_example",
    "retryable": false,
    "details": {}
  }
}
```

### 503 · `temporarily_unavailable`

A dependency, cluster readiness condition, or capacity limit prevents this operation.

Inspect retryable and details. Retry only when permitted, preserving the idempotency key for the same write.

```json
{
  "error": {
    "code": "temporarily_unavailable",
    "message": "A dependency, cluster readiness condition, or capacity limit prevents this operation.",
    "request_id": "req_example",
    "retryable": true,
    "details": {}
  }
}
```

### 500 · `internal_error`

An unexpected server failure prevented this request from completing.

Retain x-request-id for investigation. Follow retryable before retrying a write.

```json
{
  "error": {
    "code": "internal_error",
    "message": "An unexpected server failure prevented this request from completing.",
    "request_id": "req_example",
    "retryable": false,
    "details": {}
  }
}
```

## Other request languages

### cURL

```bash
curl -sS "$GRAPHON_ENGINE_URL/namespaces/acme/collections/incident-logs" \
  -H "Authorization: Bearer $GRAPHON_ENGINE_API_KEY"
```

### Python

```python
import json
import os
import urllib.request

request = urllib.request.Request(
    os.environ["GRAPHON_ENGINE_URL"] + "/namespaces/acme/collections/incident-logs",
    headers={
        "Authorization": "Bearer " + os.environ["GRAPHON_ENGINE_API_KEY"],
    },
    method="GET",
)
with urllib.request.urlopen(request) as response:
    print(response.read().decode())
```

### JavaScript

```javascript
const response = await fetch(process.env.GRAPHON_ENGINE_URL + "/namespaces/acme/collections/incident-logs", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.GRAPHON_ENGINE_API_KEY}`,
  },
});
console.log(response.status, await response.text());
```

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.