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

# List Entities

> Retrieve knowledge graph entities with filtering, search, and pagination

# List Entities

Returns knowledge graph entities (nodes) ordered by PageRank. Supports filtering by category, kind, and community ID, plus keyword search across labels and descriptions.

## Request

```
GET /api/v1/graph/entities
```

### Headers

| Header          | Required | Description                           |
| --------------- | -------- | ------------------------------------- |
| `Authorization` | Yes      | API key in `Bearer snorbe_...` format |

### Query Parameters

| Parameter               | Type      | Required | Default | Description                                 |
| ----------------------- | --------- | -------- | ------- | ------------------------------------------- |
| `category`              | `string`  | No       | -       | Filter by exact category match              |
| `kind`                  | `string`  | No       | -       | Filter by exact kind match                  |
| `communityId`           | `integer` | No       | -       | Filter by community cluster ID              |
| `search`                | `string`  | No       | -       | Keyword search across label and description |
| `metadataKeyword`       | `string`  | No       | -       | Keyword search within metadata JSON         |
| `includeOthersEntities` | `boolean` | No       | `false` | Include other members' entities             |
| `limit`                 | `integer` | No       | `30`    | Items per page (1–100)                      |
| `cursor`                | `string`  | No       | -       | `nextCursor` from previous page             |

## Response

```json theme={null}
{
  "entities": [
    {
      "id": "clxxx001",
      "label": "Lithium-Ion Battery",
      "category": "Technology",
      "kind": "battery",
      "description": "A type of rechargeable battery",
      "metadata": { "url": { "value": "https://...", "type": "text" } },
      "pagerank": 0.045,
      "communityId": 3,
      "createdAt": "2026-01-15T10:30:00.000Z",
      "updatedAt": "2026-03-20T14:22:00.000Z"
    }
  ],
  "nextCursor": "clxxx031",
  "totalCount": 1296
}
```

### Response Fields

| Field                    | Type             | Description                               |
| ------------------------ | ---------------- | ----------------------------------------- |
| `entities`               | `object[]`       | Entity array (PageRank descending)        |
| `entities[].id`          | `string`         | Entity ID                                 |
| `entities[].label`       | `string`         | Entity name                               |
| `entities[].category`    | `string`         | Category                                  |
| `entities[].kind`        | `string`         | Kind                                      |
| `entities[].description` | `string`         | Description                               |
| `entities[].metadata`    | `object \| null` | Metadata key-value pairs                  |
| `entities[].pagerank`    | `number`         | PageRank score                            |
| `entities[].communityId` | `number`         | Community cluster ID                      |
| `nextCursor`             | `string \| null` | Cursor for next page (`null` = last page) |
| `totalCount`             | `number`         | Total count after filtering               |

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  # All entities (PageRank order)
  curl "https://app.snorbe.deskrex.ai/api/v1/graph/entities?limit=30" \
    -H "Authorization: Bearer snorbe_your_api_key_here"

  # Filter by category
  curl "https://app.snorbe.deskrex.ai/api/v1/graph/entities?category=Technology&limit=30" \
    -H "Authorization: Bearer snorbe_your_api_key_here"

  # Keyword search
  curl "https://app.snorbe.deskrex.ai/api/v1/graph/entities?search=battery&limit=10" \
    -H "Authorization: Bearer snorbe_your_api_key_here"
  ```

  ```python Python theme={null}
  import requests

  resp = requests.get(
      "https://app.snorbe.deskrex.ai/api/v1/graph/entities",
      params={"category": "Technology", "limit": 30},
      headers={"Authorization": "Bearer snorbe_your_api_key_here"},
  )
  data = resp.json()
  print(f"Found {data['totalCount']} entities")
  for e in data["entities"]:
      print(f"  {e['label']} (pr={e['pagerank']})")
  ```

  ```typescript TypeScript theme={null}
  const params = new URLSearchParams({ category: "Technology", limit: "30" });
  const resp = await fetch(
    `https://app.snorbe.deskrex.ai/api/v1/graph/entities?${params}`,
    { headers: { Authorization: "Bearer snorbe_your_api_key_here" } },
  );
  const data = await resp.json();
  console.log(`Found ${data.totalCount} entities`);
  for (const e of data.entities) {
    console.log(`  ${e.label} (pr=${e.pagerank})`);
  }
  ```
</CodeGroup>

## Error Responses

| HTTP Status | Code                | Description                          |
| ----------- | ------------------- | ------------------------------------ |
| 401         | `UNAUTHORIZED`      | Invalid, expired, or missing API key |
| 429         | `TOO_MANY_REQUESTS` | Rate limit exceeded                  |