Ctrlk
Schedule a DemoMeet with usTo App
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Segments (Beta)

Segment management endpoints

List filterable segment fields

get

Returns the fields that can be used in segment filter expressions. Call /segments/filters/ for valid values within the provider scope.

Path parameters
org_idstring · uuidRequired
Query parameters
providerstring · enumRequired

Cloud provider (aws, azure, gcp)

Example: awsPossible values:
Responses
200

OK

application/json
namestringRequired
fieldstringRequired
typestring · enumRequiredPossible values:
get/beta/v1/org/{org_id}/segments/filters
GET /beta/v1/org/{org_id}/segments/filters?provider=aws HTTP/1.1
Accept: */*

[
  {
    "name": "text",
    "field": "text",
    "type": "boolean"
  }
]

Get valid values for a segment filter field

get

Returns the distinct values for a given segment filter field, scoped to the provider, org, current attribution, and active integrations.

Path parameters
org_idstring · uuidRequired
fieldstring · min: 1Required
Query parameters
providerstring · enumRequired

Cloud provider (aws, azure, gcp)

Example: awsPossible values:
Responses
200

OK

application/json
or
or
or
or
or
or
or
or
or
or
or
get/beta/v1/org/{org_id}/segments/filters/{field}
GET /beta/v1/org/{org_id}/segments/filters/{field}?provider=aws HTTP/1.1
Accept: */*

{
  "name": "text",
  "field": "text",
  "type": "boolean",
  "filters": [
    {
      "field": "text",
      "value": "text",
      "op": "="
    }
  ]
}

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

monthly_budgetnumber · nullableOptional

User-defined monthly spend budget for this segment, in USD. Null if no budget has been set.

get/beta/v1/org/{org_id}/segments
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,
    "monthly_budget": 1
  }
]

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
namestringRequired

Segment name

providerstring · enumRequired

Cloud provider (aws, azure, gcp)

Possible values:
descriptionstring · nullableOptional

Human-readable description

Default: null
Responses
201

Created

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

monthly_budgetnumber · nullableOptional

User-defined monthly spend budget for this segment, in USD. Null if no budget has been set.

post/beta/v1/org/{org_id}/segments
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,
  "monthly_budget": 1
}

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

monthly_budgetnumber · nullableOptional

User-defined monthly spend budget for this segment, in USD. Null if no budget has been set.

get/beta/v1/org/{org_id}/segments/{segment_id}
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,
  "monthly_budget": 1
}
PreviousMoneyback Guarantees (Beta)
NextInvoices (Beta)

Last updated

Was this helpful?