Segments (Beta)

Segment management endpoints

Get available segment filter fields and values

get

Returns the valid filter fields and their possible values for building segment filter parameters. Field names in the response can be used directly as the 'field' value in filter expressions.

Path parameters

org_idstring · uuidRequired

Query parameters

providerstring · enumRequired

Cloud provider (aws, azure, gcp)

Example: awsPossible values:

Responses

200

OK

application/json

integration_idstring[]Optional

Available integration IDs

account_idstring[]Optional

Available cloud account IDs

servicestring[]Optional

Available cloud service names

regionstring[]Optional

Available cloud regions

operating_systemstring[]Optional

Available operating systems (AWS only)

tenancystring[]Optional

Available tenancy types (AWS only)

instance_familystring[]Optional

Available instance families (AWS only)

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

405

Method not allowed

application/json

409

Conflict

application/json

422

Unprocessable Content

application/json

500

Internal server error

application/json

default

Default error response

application/json

get

/beta/v1/org/{org_id}/segments/filters

HTTPcURLJavaScriptPython

GET /beta/v1/org/{org_id}/segments/filters?provider=aws HTTP/1.1
Accept: */*

{
  "integration_id": [
    "text"
  ],
  "account_id": [
    "text"
  ],
  "service": [
    "text"
  ],
  "region": [
    "text"
  ],
  "operating_system": [
    "text"
  ],
  "tenancy": [
    "text"
  ],
  "instance_family": [
    "text"
  ],
  "tags": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  }
}

List segments

get

Returns all segments for the specified provider with pre-aggregated monthly metrics.

Path parameters

org_idstring · uuidRequired

Query parameters

providerstring · enumRequired

Cloud provider (aws, azure, gcp)

Example: awsPossible values:

Responses

200

OK

application/json

idstringOptional

Unique segment identifier

namestringOptional

Segment name

providerstring · enumOptional

Cloud provider (aws, azure, gcp)

Possible values:

is_system_generatedbooleanOptional

True if this segment was created automatically by the system (e.g. the provider-resources default segment). Describes origin, not role — system-generated segments are immutable.

descriptionstring · nullableOptional

Human-readable description of the segment

statusstring · enumOptional

Segment status: 'new' means the segment was just created and metrics data is not yet available; 'completed' means data has been populated and the segment can be used with daily metrics endpoints.

Possible values:

filtersanyRead-onlyOptional

The segment's filter configuration, in the same format accepted by create_segment. Excludes the provider filter (already shown in the provider field).

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

405

Method not allowed

application/json

409

Conflict

application/json

422

Unprocessable Content

application/json

500

Internal server error

application/json

default

Default error response

application/json

get

/beta/v1/org/{org_id}/segments

HTTPcURLJavaScriptPython

GET /beta/v1/org/{org_id}/segments?provider=aws HTTP/1.1
Accept: */*

[
  {
    "id": "text",
    "name": "text",
    "provider": "aws",
    "is_system_generated": true,
    "description": "text",
    "status": "new",
    "filters": null
  }
]

Create a new segment

post

Creates a new segment with the specified filter configuration. The provider filter is injected automatically — only include filters for resource attributes you want to narrow on.

Path parameters

org_idstring · uuidRequired

Body

application/json

namestringRequired

Segment name

providerstring · enumRequired

Cloud provider (aws, azure, gcp)

Possible values:

descriptionstring · nullableOptional

Human-readable description

Default: null

Responses

201

Created

application/json

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

405

Method not allowed

application/json

409

Conflict

application/json

422

Unprocessable Content

application/json

500

Internal server error

application/json

default

Default error response

application/json

post

/beta/v1/org/{org_id}/segments

HTTPcURLJavaScriptPython

POST /beta/v1/org/{org_id}/segments HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 102

{
  "name": "text",
  "provider": "aws",
  "filters": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "description": "text"
}

{
  "id": "text",
  "name": "text",
  "provider": "aws",
  "is_system_generated": true,
  "description": "text",
  "status": "new",
  "filters": null
}

Get segment details

get

Returns details for a single segment including monthly metrics.

Path parameters

org_idstring · uuidRequired

segment_idstring · uuidRequired

Responses

200

OK

application/json

idstringOptional

Unique segment identifier

namestringOptional

Segment name

providerstring · enumOptional

Cloud provider (aws, azure, gcp)

Possible values:

is_system_generatedbooleanOptional

True if this segment was created automatically by the system (e.g. the provider-resources default segment). Describes origin, not role — system-generated segments are immutable.

descriptionstring · nullableOptional

Human-readable description of the segment

statusstring · enumOptional

Segment status: 'new' means the segment was just created and metrics data is not yet available; 'completed' means data has been populated and the segment can be used with daily metrics endpoints.

Possible values:

filtersanyRead-onlyOptional

The segment's filter configuration, in the same format accepted by create_segment. Excludes the provider filter (already shown in the provider field).

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

405

Method not allowed

application/json

409

Conflict

application/json

500

Internal server error

application/json

default

Default error response

application/json

get

/beta/v1/org/{org_id}/segments/{segment_id}

HTTPcURLJavaScriptPython

GET /beta/v1/org/{org_id}/segments/{segment_id} HTTP/1.1
Accept: */*

{
  "id": "text",
  "name": "text",
  "provider": "aws",
  "is_system_generated": true,
  "description": "text",
  "status": "new",
  "filters": null
}