---
title: "Custom Dimensions APIs"
slug: "custom-dimensions-apis"
description: "Explore Kentik's API for managing custom dimensions and populators, including creation, retrieval, updates, and deletions in your environment."
tags: ["Custom Dimensions", "Populators"]
updated: 2026-10-14T19:11:27Z
published: 2026-10-14T19:11:27Z
canonical: "kb.kentik.com/custom-dimensions-apis"
---

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

# Custom Dimensions APIs

This article provides programmatic specifications for creating, retrieving, updating, and deleting custom dimensions and their populators in your Kentik environment.

A custom dimension is a user-defined field. Its populators are the rules that determine which flow records are assigned each value of that field.

- **API Version:** `/custom_dimensions/v202411alpha1`
- **Protocol:** HTTPS
- **Format:** JSON

> [!NOTE]
> **Notes**:
> 
> - This API is in alpha (`v202411alpha1`).
> - See [**Kentik APIs**](/v1/docs/apis-overview) for base URLs, authentication specifications, and rate limits.
> - The [Create a Custom Dimension](/v1/docs/custom-dimensions-apis#create-a-custom-dimension) endpoint uses the unversioned path `/v1/customdimension`. All other endpoints use the versioned `/custom_dimensions/v202411alpha1` path.

For background on the purpose and usage of custom dimensions and populators, see [**Custom Dimensions**](/v1/docs/custom-dimensions).

## Custom Dimension Endpoints

### List Custom Dimensions

Returns an array of custom dimension objects, each containing information about an individual custom dimension and its populators. For details on the returned payload structure, see [**List Response**](/v1/docs/custom-dimensions-apis#list-response-dimensions).

**HTTP Request**:

`GET /custom_dimensions/v202411alpha1`

> [!TIP]
> **Tip**: The response includes every custom dimension together with all of its populators, so it can be large. To retrieve a single dimension, use [**Get a Custom Dimension**](/v1/docs/custom-dimensions-apis#get-a-custom-dimension).

#### cURL Example

The following is an example request to the List Custom Dimensions endpoint.

```bash
curl -X GET "https://grpc.api.kentik.com/custom_dimensions/v202411alpha1" \
  -H "X-CH-Auth-Email: your-email@company.com" \
  -H "X-CH-Auth-API-Token: your-api-token"
```

Example response:

```json
{
  "dimensions": [
    {
      "id": "142188",
      "name": "c_region",
      "type": "string",
      "description": "Customer Region",
      "populators": [
        {
          "id": "9635828926",
          "value": "us-east",
          "direction": "EITHER",
          "deviceName": [],
          "deviceType": [],
          "site": [],
          "interfaceName": [],
          "addr": [
            "10.1.0.0/16",
            "10.2.0.0/16",
            "10.3.0.0/16"
          ],
          "port": [
            443
          ],
          "tcpFlags": 0,
          "protocol": [
            6
          ],
          "asn": [],
          "lasthopAsName": [],
          "nexthopAsn": [],
          "nexthopAsName": [],
          "nexthop": [],
          "bgpAspath": [],
          "bgpCommunity": [],
          "mac": [],
          "country": [],
          "vlans": [],
          "user": "67890",
          "createdDate": "2026-10-05T23:21:38.464Z",
          "updatedDate": "2026-10-05T23:21:38.464Z",
          "addrCount": 3,
          "macCount": 0,
          "extendedFields": {}
        }
      ],
      "companyId": "12345",
      "createdDate": "2026-10-05T23:21:35.046Z",
      "updatedDate": "2026-10-05T23:21:35.046Z"
    }
  ]
}
```

> [!NOTE]
> **Note**: The example above is abbreviated. The actual response contains every custom dimension in your account.

### Get a Custom Dimension

Returns a custom dimension object containing information about an individual custom dimension, including its populators. See [**Get Response**](/v1/docs/custom-dimensions-apis#get-response-dimension) for payload structure details.

**HTTP Request**:

`GET /custom_dimensions/v202411alpha1/{customDimensionId}`

#### Path Parameters

| Parameter | Placement | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `customDimensionId` | path | string | Yes | Unique identifier of the custom dimension. |

#### cURL Example

The following is a sample request to the Get a Custom Dimension endpoint.

```bash
curl -X GET "https://grpc.api.kentik.com/custom_dimensions/v202411alpha1/142188" \
  -H "X-CH-Auth-Email: your-email@company.com" \
  -H "X-CH-Auth-API-Token: your-api-token"
```

Example response:

```json
{
  "dimension": {
    "id": "142188",
    "name": "c_region",
    "type": "string",
    "description": "Customer Region",
    "populators": [
      {
        "id": "9635828926",
        "value": "us-east",
        "direction": "EITHER",
        "deviceName": [],
        "deviceType": [],
        "site": [],
        "interfaceName": [],
        "addr": [
          "10.1.0.0/16",
          "10.2.0.0/16",
          "10.3.0.0/16"
        ],
        "port": [
          443
        ],
        "tcpFlags": 0,
        "protocol": [
          6
        ],
        "asn": [],
        "lasthopAsName": [],
        "nexthopAsn": [],
        "nexthopAsName": [],
        "nexthop": [],
        "bgpAspath": [],
        "bgpCommunity": [],
        "mac": [],
        "country": [],
        "vlans": [],
        "user": "67890",
        "createdDate": "2026-10-05T23:21:38.464Z",
        "updatedDate": "2026-10-05T23:21:38.464Z",
        "addrCount": 3,
        "macCount": 0,
        "extendedFields": {}
      }
    ],
    "companyId": "12345",
    "createdDate": "2026-10-05T23:21:35.046Z",
    "updatedDate": "2026-10-05T23:21:35.046Z"
  }
}
```

### Create a Custom Dimension

Creates a custom dimension and returns a custom dimension object containing information about it. The request body is a [**Custom Dimension**](/v1/docs/custom-dimensions-apis#custom-dimension-object) object. See [**Create Response**](/v1/docs/custom-dimensions-apis#create-response-dimension) for payload structure details.

**HTTP Request**:

`POST /v1/customdimension`

#### Request Body Fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | The name of the custom dimension. Must start with `c_`. Valid characters: alphanumeric and underscores. Length: 3 to 20. |
| `type` | string | Yes | Type of the custom dimension. Valid values: `string` or `uint32`. |
| `description` | string | Yes | The display name of the custom dimension. Valid characters: alphanumeric, spaces, dashes, and underscores. Length: 2 to 30. |

> [!NOTE]
> **Notes**:
> 
> - This endpoint uses the unversioned path `/v1/customdimension`. Sending a `POST` to `/custom_dimensions/v202411alpha1` returns HTTP 415.
> - `populators` and the other read-only fields of the [**Custom Dimension**](/v1/docs/custom-dimensions-apis#custom-dimension-object) object are not accepted in the request. Add populators with the [**Create a Populator**](/v1/docs/custom-dimensions-apis#create-a-populator) endpoint after creating the dimension.

#### cURL Example

The following is a sample request to the Create a Custom Dimension endpoint.

```bash
curl -X POST "https://grpc.api.kentik.com/v1/customdimension" \
  -H "X-CH-Auth-Email: your-email@company.com" \
  -H "X-CH-Auth-API-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{"name": "c_region", "type": "string", "description": "Customer Region"}'
```

Example response:

```json
{
  "dimension": {
    "id": "142188",
    "name": "c_region",
    "type": "string",
    "description": "Customer Region",
    "populators": [],
    "companyId": "12345",
    "createdDate": "2026-10-05T23:21:35.046Z",
    "updatedDate": "2026-10-05T23:21:35.046Z"
  }
}
```

### Update a Custom Dimension

Updates a custom dimension and returns the updated custom dimension object. The request body is a [**Custom Dimension**](/v1/docs/custom-dimensions-apis#custom-dimension-object) object with the fields described in [**Create a Custom Dimension**](/v1/docs/custom-dimensions-apis#create-a-custom-dimension). See [**Update Response**](/v1/docs/custom-dimensions-apis#update-response-dimension) for payload structure details.

**HTTP Request**:

`PUT /custom_dimensions/v202411alpha1/{customDimensionId}`

#### Path Parameters

| Parameter | Placement | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `customDimensionId` | path | string | Yes | Unique identifier of the custom dimension. |

> [!NOTE]
> **Notes**:
> 
> - `name`, `type`, and `description` are all required. The API rejects a request that omits `description` with HTTP 400.
> - The response body doesn’t include populators. To retrieve them, use the [**Get a Custom Dimension**](/v1/docs/custom-dimensions-apis#get-a-custom-dimension) endpoint.

#### cURL Example

The following is a sample request to the Update a Custom Dimension endpoint.

```bash
curl -X PUT "https://grpc.api.kentik.com/custom_dimensions/v202411alpha1/142188" \
  -H "X-CH-Auth-Email: your-email@company.com" \
  -H "X-CH-Auth-API-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{"name": "c_region", "type": "string", "description": "Customer Region (updated)"}'
```

Example response:

```json
{
  "dimension": {
    "id": "142188",
    "name": "c_region",
    "type": "string",
    "description": "Customer Region (updated)",
    "populators": [],
    "companyId": "12345",
    "createdDate": "2026-10-05T23:21:35.046Z",
    "updatedDate": "2026-10-05T23:21:37.795Z"
  }
}
```

### Delete a Custom Dimension

Deletes a custom dimension. On success, the endpoint returns an empty JSON object (see [**Delete Response**](/v1/docs/custom-dimensions-apis#delete-response-dimension)).

**HTTP Request**:

`DELETE /custom_dimensions/v202411alpha1/{customDimensionId}`

#### Path Parameters

| Parameter | Placement | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `customDimensionId` | path | string | Yes | Unique identifier of the custom dimension. |

> [!NOTE]
> **Note**: Deleting a custom dimension cannot be undone.

#### cURL Example

The following is a sample request to the Delete a Custom Dimension endpoint.

```bash
curl -X DELETE "https://grpc.api.kentik.com/custom_dimensions/v202411alpha1/142188" \
  -H "X-CH-Auth-Email: your-email@company.com" \
  -H "X-CH-Auth-API-Token: your-api-token"
```

Example response:

```json
{}
```

## Populator Endpoints

### Create a Populator

Creates a populator for a custom dimension and returns a populator object containing information about it. The request body is a [**Populator**](/v1/docs/custom-dimensions-apis#populator-object) object. See [**Create Response**](/v1/docs/custom-dimensions-apis#create-response-populator) for payload structure details.

**HTTP Request**:

`POST /custom_dimensions/v202411alpha1/{customDimensionId}/populator`

#### Path Parameters

| Parameter | Placement | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `customDimensionId` | path | string | Yes | Unique identifier of the custom dimension. |

> [!NOTE]
> **Notes**:
> 
> - Within a match field that accepts multiple values, a match results when any one of the values matches.
> - The valid `value` format depends on the custom dimension `type`. For `string` dimensions, use 1 to 128 alphanumeric characters, spaces, dashes, or underscores. For `uint32` dimensions, use a number from 0 to 4294967295.
> - Lowercase `direction` values (`src`, `dst`, `either`) are accepted. The response returns the value in uppercase.

#### cURL Example

The following is a sample request to the Create a Populator endpoint.

```bash
curl -X POST "https://grpc.api.kentik.com/custom_dimensions/v202411alpha1/142188/populator" \
  -H "X-CH-Auth-Email: your-email@company.com" \
  -H "X-CH-Auth-API-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{"value": "us-east", "direction": "either", "addr": ["10.1.0.0/16", "10.2.0.0/16", "10.3.0.0/16"], "port": [443], "protocol": [6]}'
```

Example response:

```json
{
  "populator": {
    "id": "9635828926",
    "value": "us-east",
    "direction": "EITHER",
    "deviceName": [],
    "deviceType": [],
    "site": [],
    "interfaceName": [],
    "addr": [
      "10.1.0.0/16",
      "10.2.0.0/16",
      "10.3.0.0/16"
    ],
    "port": [
      443
    ],
    "tcpFlags": 0,
    "protocol": [
      6
    ],
    "asn": [],
    "lasthopAsName": [],
    "nexthopAsn": [],
    "nexthopAsName": [],
    "nexthop": [],
    "bgpAspath": [],
    "bgpCommunity": [],
    "mac": [],
    "country": [],
    "vlans": [],
    "user": "67890",
    "createdDate": "2026-10-05T23:21:38.464Z",
    "updatedDate": "2026-10-05T23:21:38.464Z",
    "addrCount": 3,
    "macCount": 0,
    "extendedFields": {}
  }
}
```

### Get a Populator

Returns a populator by custom dimension ID and populator ID. See [**Get Response**](/v1/docs/custom-dimensions-apis#get-response-populator) for payload structure details.

**HTTP Request**:

`GET /custom_dimensions/v202411alpha1/{customDimensionId}/populator/{populatorId}`

#### Path and Query Parameters

| Parameter | Placement | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `customDimensionId` | path | string | Yes | Unique identifier of the custom dimension. |
| `populatorId` | path | string | Yes | Unique identifier of the populator. |
| `fieldLimit` | query | int64 | No | Limits the number of values returned in list fields such as `addr`. Count fields such as `addrCount` still report the total. |

#### cURL Example

The following is a sample request to the Get a Populator endpoint.

```bash
curl -X GET "https://grpc.api.kentik.com/custom_dimensions/v202411alpha1/142188/populator/9635828926" \
  -H "X-CH-Auth-Email: your-email@company.com" \
  -H "X-CH-Auth-API-Token: your-api-token"
```

Example response:

```json
{
  "populator": {
    "id": "9635828926",
    "value": "us-east",
    "direction": "EITHER",
    "deviceName": [],
    "deviceType": [],
    "site": [],
    "interfaceName": [],
    "addr": [
      "10.1.0.0/16",
      "10.2.0.0/16",
      "10.3.0.0/16"
    ],
    "port": [
      443
    ],
    "tcpFlags": 0,
    "protocol": [
      6
    ],
    "asn": [],
    "lasthopAsName": [],
    "nexthopAsn": [],
    "nexthopAsName": [],
    "nexthop": [],
    "bgpAspath": [],
    "bgpCommunity": [],
    "mac": [],
    "country": [],
    "vlans": [],
    "user": "67890",
    "createdDate": "2026-10-05T23:21:38.464Z",
    "updatedDate": "2026-10-05T23:21:38.464Z",
    "addrCount": 3,
    "macCount": 0,
    "extendedFields": {}
  }
}
```

#### Limit Returned Values Example

To limit the number of values returned in list fields, add the `fieldLimit` query parameter. The following sample request returns only the first `addr` value, while `addrCount` still reports the total of 3:

```bash
curl -X GET "https://grpc.api.kentik.com/custom_dimensions/v202411alpha1/142188/populator/9635828926?fieldLimit=1" \
  -H "X-CH-Auth-Email: your-email@company.com" \
  -H "X-CH-Auth-API-Token: your-api-token"
```

Example response:

```json
{
  "populator": {
    "id": "9635828926",
    "value": "us-east",
    "direction": "EITHER",
    "deviceName": [],
    "deviceType": [],
    "site": [],
    "interfaceName": [],
    "addr": [
      "10.1.0.0/16"
    ],
    "port": [
      443
    ],
    "tcpFlags": 0,
    "protocol": [
      6
    ],
    "asn": [],
    "lasthopAsName": [],
    "nexthopAsn": [],
    "nexthopAsName": [],
    "nexthop": [],
    "bgpAspath": [],
    "bgpCommunity": [],
    "mac": [],
    "country": [],
    "vlans": [],
    "user": "67890",
    "createdDate": "2026-10-05T23:21:38.464Z",
    "updatedDate": "2026-10-05T23:21:38.464Z",
    "addrCount": 3,
    "macCount": 0,
    "extendedFields": {}
  }
}
```

### Update a Populator

Updates a populator and returns the updated populator object. The request body is a [**Populator**](/v1/docs/custom-dimensions-apis#populator-object) object. See [**Update Response**](/v1/docs/custom-dimensions-apis#update-response-populator) for payload structure details.

**HTTP Request**:

`PUT /custom_dimensions/v202411alpha1/{customDimensionId}/populator/{populatorId}`

#### Path Parameters

| Parameter | Placement | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `customDimensionId` | path | string | Yes | Unique identifier of the custom dimension. |
| `populatorId` | path | string | Yes | Unique identifier of the populator. |

> [!NOTE]
> **Note**: A populator must include at least one match field (for example `addr`, `port`, or `protocol`). A request that contains only `value` is rejected with HTTP 400 and the message `Missing criteria`. The existing populator is not changed.

#### cURL Example

The following is a sample request to the Update a Populator endpoint.

```bash
curl -X PUT "https://grpc.api.kentik.com/custom_dimensions/v202411alpha1/142188/populator/9635828926" \
  -H "X-CH-Auth-Email: your-email@company.com" \
  -H "X-CH-Auth-API-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{"value": "us-east", "direction": "src", "addr": ["10.1.0.0/16"], "port": [443], "protocol": [6]}'
```

Example response:

```json
{
  "populator": {
    "id": "9635828926",
    "value": "us-east",
    "direction": "SRC",
    "deviceName": [],
    "deviceType": [],
    "site": [],
    "interfaceName": [],
    "addr": [
      "10.1.0.0/16"
    ],
    "port": [
      443
    ],
    "tcpFlags": 0,
    "protocol": [
      6
    ],
    "asn": [],
    "lasthopAsName": [],
    "nexthopAsn": [],
    "nexthopAsName": [],
    "nexthop": [],
    "bgpAspath": [],
    "bgpCommunity": [],
    "mac": [],
    "country": [],
    "vlans": [],
    "user": "67890",
    "createdDate": "2026-10-05T23:21:38.464Z",
    "updatedDate": "2026-10-05T23:21:40.860Z",
    "addrCount": 1,
    "macCount": 0,
    "extendedFields": {}
  }
}
```

### Delete a Populator

Use this endpoint to delete a populator. On success, you’re returned an empty JSON object (see [**Delete Response**](/v1/docs/custom-dimensions-apis#delete-response-populator)).

**HTTP Request**:

`DELETE /custom_dimensions/v202411alpha1/{customDimensionId}/populator/{populatorId}`

#### Path Parameters

| Parameter | Placement | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `customDimensionId` | path | string | Yes | Unique identifier of the custom dimension. |
| `populatorId` | path | string | Yes | Unique identifier of the populator. |

> [!NOTE]
> **Note**: Deleting a populator cannot be undone.

#### cURL Example

The following is a sample request to the Delete a Populator endpoint.

```bash
curl -X DELETE "https://grpc.api.kentik.com/custom_dimensions/v202411alpha1/142188/populator/9635828926" \
  -H "X-CH-Auth-Email: your-email@company.com" \
  -H "X-CH-Auth-API-Token: your-api-token"
```

Example response:

```json
{}
```

### Get a Populator Field

Returns the values of a single extended field of a populator, by custom dimension ID, populator ID, and field name. Extended fields appear in the `extendedFields` object of the [**Populator**](/v1/docs/custom-dimensions-apis#populator-object) object. See [**Get Field Response**](/v1/docs/custom-dimensions-apis#get-field-response) for payload structure details.

**HTTP Request**:

`GET /custom_dimensions/v202411alpha1/{customDimensionId}/populator/{populatorId}/field/{fieldName}`

#### Path and Query Parameters

| Parameter | Placement | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `customDimensionId` | path | string | Yes | Unique identifier of the custom dimension. |
| `populatorId` | path | string | Yes | Unique identifier of the populator. |
| `fieldName` | path | string | Yes | Name of the extended field, as listed in the populator's `extendedFields` object (for example, `str17`). |
| `offset` | query | int32 | No | Pagination offset. |
| `limit` | query | int32 | No | Number of values to return per page. |

> [!NOTE]
> **Notes**:
> 
> - This endpoint retrieves extended fields only. For example, requesting a standard match field such as `addr` returns HTTP 404 with the message `Populator field not found`.
> - [**Get a Populator**](/v1/docs/custom-dimensions-apis#get-a-populator) returns standard match fields directly in the [**Populator**](/v1/docs/custom-dimensions-apis#populator-object) object. To limit the number of values returned for them, use the `fieldLimit` parameter.

> [!TIP]
> **Tip**: Combine `limit` and `offset` to page through results. Use `totalCount` in the response to determine when you have retrieved every value.

#### cURL Example

The following is a sample request to the Get a Populator Field endpoint.

```bash
curl -X GET "https://grpc.api.kentik.com/custom_dimensions/v202411alpha1/142188/populator/9635828926/field/str17?offset=0&limit=100" \
  -H "X-CH-Auth-Email: your-email@company.com" \
  -H "X-CH-Auth-API-Token: your-api-token"
```

Example response:

```json
{
  "totalCount": 2,
  "offset": 0,
  "limit": 100,
  "extendedFields": {
    "str17": {
      "value": [
        "value-1",
        "value-2"
      ]
    }
  }
}
```

## Standard API Responses & Errors

### List Response (Custom Dimension)

When calling the List Custom Dimensions endpoint, the returned JSON wraps the result set in a `dimensions` array:

```json
{
  "dimensions": [
    { /* Custom Dimension Object 1 */ },
    { /* Custom Dimension Object 2 */ }
  ]
}
```

### Get Response (Custom Dimension)

When calling the Get a Custom Dimension endpoint, the returned JSON wraps the single result in a `dimension` object:

```json
{
  "dimension": { /* Custom Dimension Object */ }
}
```

### Create Response (Custom Dimension)

When calling the Create a Custom Dimension endpoint, the returned JSON wraps the new custom dimension in a `dimension` object:

```json
{
  "dimension": { /* Custom Dimension Object */ }
}
```

### Update Response (Custom Dimension)

When calling the Update a Custom Dimension endpoint, the returned JSON wraps the updated custom dimension in a `dimension` object. The `populators` array is empty:

```json
{
  "dimension": { /* Custom Dimension Object */ }
}
```

### Delete Response (Custom Dimension)

When calling the Delete a Custom Dimension endpoint, the returned JSON is an empty object:

```json
{}
```

### Get Response (Populator)

When calling the Get a Populator endpoint, the returned JSON wraps the single result in a `populator` object:

```json
{
  "populator": { /* Populator Object */ }
}
```

### Create Response (Populator)

When calling the Create a Populator endpoint, the returned JSON wraps the new populator in a `populator` object:

```json
{
  "populator": { /* Populator Object */ }
}
```

### Update Response (Populator)

When calling the Update a Populator endpoint, the returned JSON wraps the updated populator in a `populator` object:

```json
{
  "populator": { /* Populator Object */ }
}
```

### Delete Response (Populator)

When calling the Delete a Populator endpoint, the returned JSON is an empty object:

```json
{}
```

### Get Field Response

When calling the Get a Populator Field endpoint, the returned JSON contains pagination details and the field values, keyed by field name:

```json
{
  "totalCount": 2,
  "offset": 0,
  "limit": 100,
  "extendedFields": {
    "str17": {
      "value": ["value-1", "value-2"]
    }
  }
}
```

### Error Response

If an API request fails, Kentik returns a standard error object containing an error code and a message.

| Field | Type | Description |
| --- | --- | --- |
| `code` | integer (int32) | The numeric error code. |
| `message` | string | A human-readable error description. The message ends with a request identifier (`errxid`). Include it when you report an issue. |
| `details` | array (protobufAny) | An array of additional error details, if applicable. |

#### HTTP Status Codes

| Status | Error Code | Meaning |
| --- | --- | --- |
| `200` | — | The request succeeded. |
| `400` | `3` | The request failed validation. For example, a dimension `name` or `type` is invalid, a required field such as `description` is missing, or a populator has no match fields. |
| `404` | `5` | The requested populator or populator field wasn’t found. |
| `415` | — | The request used an unsupported method and path combination, such as a `POST` to `/custom_dimensions/v202411alpha1`. Create custom dimensions with `/v1/customdimension`. |
| `500` | `13` | The API can return this status with the message `internal error` when the requested custom dimension ID doesn’t exist. |

#### Example Error Responses

Invalid dimension name (HTTP 400):

```json
{
  "code": 3,
  "message": "internal validation (col_name: Must only contain alpha-numeric characters and underscores) (errxid db2321rtkfgg0gtbfcw0)",
  "details": []
}
```

Invalid dimension type (HTTP 400):

```json
{
  "code": 3,
  "message": "internal validation (col_type: Unrecognized type: banana) (errxid db2321rtkfgg0gtbfcwg)",
  "details": []
}
```

Missing required field (HTTP 400):

```json
{
  "code": 3,
  "message": "Missing required fields on dimension {...} (errxid db239m64km2g068py7fg)",
  "details": []
}
```

Populator without match fields (HTTP 400):

```json
{
  "code": 3,
  "message": "422 - {\"error\":\"Missing criteria\"} (errxid db239n6tkfgg068g9g00)",
  "details": []
}
```

Custom dimension not found (HTTP 500):

```json
{
  "code": 13,
  "message": "internal error (name:error type:object) (errxid db239nptkfgg0d9rp670)",
  "details": []
}
```

Populator not found (HTTP 404):

```json
{
  "code": 5,
  "message": "Populator not found (errxid db2321r4km2g0f1f7ev0)",
  "details": []
}
```

## Response Fields

### Custom Dimension Object

The `Custom Dimension` object defines the attributes of a custom dimension.

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Unique identifier for the custom dimension. Read-only. |
| `name` | string | The name of the custom dimension. Must start with `c_`. Valid characters: alphanumeric and underscores. Length: 3 to 20. Required. |
| `type` | string | Type of the custom dimension. Valid values: `string` or `uint32`. Required. |
| `description` | string | The display name of the custom dimension. Valid characters: alphanumeric, spaces, dashes, and underscores. Length: 2 to 30. Required. |
| `populators` | array (Populator) | Populators associated with this custom dimension (see [**Populator Object**](/v1/docs/custom-dimensions-apis#populator-object)). Read-only. |
| `companyId` | string | The system-assigned ID of the customer. Read-only. |
| `createdDate` | string (date-time) | Date-time of custom dimension creation, in UTC. Read-only. |
| `updatedDate` | string (date-time) | Date-time of the most recent custom dimension edit, in UTC. Read-only. |

### Populator Object

The `Populator` object defines the rule that assigns a value of a custom dimension to matching flow records. Each match field is optional, but a populator must specify at least one of them. When you specify multiple values in an array field, a match results when any one of the values matches.

#### General Fields

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Unique identifier for the populator. Read-only. |
| `value` | string | The value of the dimension. For `string` dimensions: alphanumeric characters, spaces, dashes, and underscores; length 1 to 128. For `uint32` dimensions: a number from 0 to 4294967295. |
| `direction` | string | The direction of the populator. Valid values: `src`, `dst`, or `either`. Lowercase values are accepted in requests. Responses return the value in uppercase (`SRC`, `DST`, `EITHER`). |
| `user` | string | The system-assigned ID of the user who created the populator. Read-only. |
| `createdDate` | string (date-time) | Date-time of populator creation, in UTC. Read-only. |
| `updatedDate` | string (date-time) | Date-time of the most recent populator edit, in UTC. Read-only. |
| `addrCount` | int64 | Number of IP addresses. Read-only. |
| `macCount` | int64 | Number of MAC addresses. Read-only. |
| `extendedFields` | object | Additional read-only fields set on the object. Each key maps to an object with a `value` array of strings. Retrieve the values of an extended field with [**Get a Populator Field**](/v1/docs/custom-dimensions-apis#get-a-populator-field). |

#### Match Fields

| Field | Type | Description |
| --- | --- | --- |
| `deviceName` | array (string) | Device names, IP addresses, or regular expressions. The populator matches when the name or IP address of a device sending flow data. |
| `deviceType` | array (string) | Device types or regular expressions. The populator matches when the device type of a device sending flow data. |
| `site` | array (string) | Site names or regular expressions. The populator matches when the site of a device sending flow data. |
| `interfaceName` | array (string) | Interface names or regular expressions. The populator matches when the name or description of an interface sending flow data. |
| `addr` | array (string) | IP addresses in IP/CIDR format. A match results when any specified address falls within a range of IPs in incoming flow. IPv6 CIDRs are allowed, and short form (e.g., `1::2/127`) is accepted. If you specify no CIDRs, the populator matches both IPv4 and IPv6 flow. If you specify only IPv4 CIDRs, the populator doesn’t match IPv6 flow. If you specify only IPv6 CIDRs, it doesn’t match IPv4 flow. |
| `port` | array (int64) | Ports (0 to 65535). A match results when any specified port matches a port number in incoming flow. |
| `tcpFlags` | int64 | TCP flags as a number from 0 to 255 representing an 8-bit pattern. A match results when the flow bit pattern and the bitmask both have a value of 1 at any of the eight positions. |
| `protocol` | array (integer, uint32) | Protocol numbers (0 to 255). A match results when any specified protocol number matches the protocol of the flow. |
| `asn` | array (int64) | Last-hop (origin) Autonomous System Number (ASN, 1 to 4294967295). A match results when any specified ASN matches the last ASN in the routing table path for the source or destination IP. |
| `lasthopAsName` | array (string) | Last-hop (origin) AS names or regular expressions. The populator matches when the name for the last ASN in the path for the source or destination IP. |
| `nexthopAsn` | array (int64) | Next-hop ASNs. A match results when any specified ASN matches the ASN of the next-hop router based on the AS (Autonomous System) path. |
| `nexthopAsName` | array (string) | Next-hop AS names or regular expressions. The populator matches when the name for the ASN of the next-hop router based on the AS path. |
| `nexthop` | array (string) | Next-hop IPv4 CIDRs, IPv6 CIDRs, or both. A match results when the next-hop IP falls within any specified range. |
| `bgpAspath` | array (string) | BGP AS path expressions. The populator matches when the AS path of the route. For example: `^3737 1212,_7801_,2906$` looks for any of those three patterns. Permitted characters: `[]*:_^$.0123456789()+?,` space, and `-`. |
| `bgpCommunity` | array (string) | BGP communities (for example, `2096:2212`) or regular expressions. The populator matches when the BGP community of the route associated with incoming flow. Permitted characters: `[]*:_^$.0123456789()+?,` space, and `-`. |
| `mac` | array (string) | MAC addresses. A match results when any specified address matches the source or destination Ethernet (L2) address. |
| `country` | array (string) | Two-character country codes. A match results when any specified code matches the source or destination country of the flow. |
| `vlans` | array (string) | VLANs, as integers or ranges of integers from 0 to 4095. |