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

Notes:

• This API is in alpha (v202411alpha1).

• See Kentik APIs for base URLs, authentication specifications, and rate limits.

• The 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.

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.

HTTP Request:

GET /custom_dimensions/v202411alpha1

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.

cURL Example

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

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:

{
  "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: 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 for payload structure details.

HTTP Request:

GET /custom_dimensions/v202411alpha1/{customDimensionId}

Path Parameters

cURL Example

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

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:

{
  "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 object. See Create Response for payload structure details.

HTTP Request:

POST /v1/customdimension

Request Body Fields

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 object are not accepted in the request. Add populators with the Create a Populator endpoint after creating the dimension.

cURL Example

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

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:

{
  "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 object with the fields described in Create a Custom Dimension. See Update Response for payload structure details.

HTTP Request:

PUT /custom_dimensions/v202411alpha1/{customDimensionId}

Path Parameters

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 endpoint.

cURL Example

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

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:

{
  "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).

HTTP Request:

DELETE /custom_dimensions/v202411alpha1/{customDimensionId}

Path Parameters

Note: Deleting a custom dimension cannot be undone.

cURL Example

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

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:

{}

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 object. See Create Response for payload structure details.

HTTP Request:

POST /custom_dimensions/v202411alpha1/{customDimensionId}/populator

Path Parameters

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.

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:

{
  "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 for payload structure details.

HTTP Request:

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

Path and Query Parameters

cURL Example

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

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:

{
  "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:

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:

{
  "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 object. See Update Response for payload structure details.

HTTP Request:

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

Path Parameters

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.

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:

{
  "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).

HTTP Request:

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

Path Parameters

Note: Deleting a populator cannot be undone.

cURL Example

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

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:

{}

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 object. See Get Field Response for payload structure details.

HTTP Request:

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

Path and Query Parameters

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 returns standard match fields directly in the Populator object. To limit the number of values returned for them, use the fieldLimit parameter.

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.

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

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

Delete Response (Custom Dimension)

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

{}

Get Response (Populator)

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

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

Create Response (Populator)

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

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

Update Response (Populator)

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

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

Delete Response (Populator)

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

{}

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:

{
  "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.

HTTP Status Codes

Example Error Responses

Invalid dimension name (HTTP 400):

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

Invalid dimension type (HTTP 400):

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

Missing required field (HTTP 400):

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

Populator without match fields (HTTP 400):

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

Custom dimension not found (HTTP 500):

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

Populator not found (HTTP 404):

{
  "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.

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

Match Fields