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

# Territories

> List territories, retrieve territory details, and view companies within a territory

## List Territories

Retrieve a paginated list of all territories in your workspace.

<ParamField query="page" type="integer" default="1">
  Page number for pagination.
</ParamField>

<ParamField query="per_page" type="integer" default="25">
  Number of territories per page.
</ParamField>

**Permission:** `territories:read`

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.getpg.ai/public-api/v1/territories?page=1&per_page=10" \
    -H "x-api-key: your_api_key"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "itemsReceived": 4,
    "curPage": 1,
    "nextPage": null,
    "prevPage": null,
    "offset": 0,
    "perPage": 25,
    "itemsTotal": 4,
    "pageTotal": 1,
    "items": [
      {
        "id": "f2b6d9b6-c4ce-4eb6-9c65-4e48fcde4dfe",
        "territory_name": "Enterprise West Coast",
        "status": "",
        "created_at": "2025-10-08T22:27:24.248Z"
      },
      {
        "id": "96951eb0-340e-4016-a3fc-c3470e76e6b6",
        "territory_name": "Mid-Market EMEA",
        "status": "",
        "created_at": "2025-10-08T22:25:14.560Z"
      }
    ]
  }
  ```
</ResponseExample>

***

## Get Territory

Retrieve information about a specific territory.

<ParamField path="territory_id" type="string" required>
  The unique identifier of the territory.
</ParamField>

**Permission:** `territories:read`

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.getpg.ai/public-api/v1/territories/{territory_id}" \
    -H "x-api-key: your_api_key"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "f2b6d9b6-c4ce-4eb6-9c65-4e48fcde4dfe",
    "territory_name": "Enterprise West Coast",
    "status": "",
    "created_at": "2025-10-08T22:27:24.248Z"
  }
  ```
</ResponseExample>

***

## List Territory Companies

<Note>
  **Early access** — this endpoint is available but not yet in the interactive API Reference.
</Note>

Retrieve the companies that belong to a specific territory, with pagination. Returns company IDs and their processing status — use `GET /companies/{company_id}` to fetch full company details.

<ParamField path="territory_id" type="string" required>
  The unique identifier of the territory.
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number for pagination.
</ParamField>

<ParamField query="per_page" type="integer" default="25">
  Number of companies per page.
</ParamField>

**Permission:** `territories:read`

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.getpg.ai/public-api/v1/territories/{territory_id}/companies?page=1&per_page=20" \
    -H "x-api-key: your_api_key"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "itemsReceived": 2,
    "curPage": 1,
    "nextPage": 2,
    "prevPage": null,
    "offset": 0,
    "perPage": 20,
    "itemsTotal": 30,
    "pageTotal": 15,
    "items": [
      {
        "id": "62fe568a-fd78-4adf-9920-bfd8cd86b7e4",
        "company_id": "0de1addb-dfe7-497c-b116-4d1a0c1ffda1",
        "status": "Completed",
        "created_at": "2026-03-24T11:54:56.348Z"
      },
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "company_id": "7d31ffcc-6567-4071-af95-6084d702e024",
        "status": "not_started",
        "created_at": "2026-03-24T11:54:56.348Z"
      }
    ]
  }
  ```
</ResponseExample>

<Note>
  Territory company items return `company_id` and `status` (e.g. `Completed`, `not_started`). To get full company details like name, industry, and employee count, call `GET /companies/{company_id}` with the `company_id` from the response.
</Note>