> For the complete documentation index, see [llms.txt](https://docs.archera.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.archera.ai/api-reference/beta-api/segments-beta.md).

# Segments (Beta)

Segment management endpoints

## List filterable segment fields

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

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Segments (Beta)","description":"Segment management endpoints"}],"paths":{"/beta/v1/org/{org_id}/segments/filters":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BaseAttribute"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Segments (Beta)"],"summary":"List filterable segment fields","description":"Returns the fields that can be used in segment filter expressions. Call /segments/filters/<field> for valid values within the provider scope."}}},"components":{"schemas":{"BaseAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["boolean","integer","float","date","datetime","time","currency","percent","string","enum","uuid","tags"]}},"required":["field","name","type"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{}},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"status":{"type":"string"},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["error","errors","message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{}},"error":{"type":"string"},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["error","errors","message","timestamp","type"],"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Get valid values for a segment filter field

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

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Segments (Beta)","description":"Segment management endpoints"}],"paths":{"/beta/v1/org/{org_id}/segments/filters/{field}":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Attribute"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Segments (Beta)"],"summary":"Get valid values for a segment filter field","description":"Returns the distinct values for a given segment filter field, scoped to the provider, org, current attribution, and active integrations."}}},"components":{"schemas":{"Attribute":{"oneOf":[{"$ref":"#/components/schemas/BooleanAttribute"},{"$ref":"#/components/schemas/UUIDAttribute"},{"$ref":"#/components/schemas/StringAttribute"},{"$ref":"#/components/schemas/IntegerAttribute"},{"$ref":"#/components/schemas/FloatAttribute"},{"$ref":"#/components/schemas/CurrencyAttribute"},{"$ref":"#/components/schemas/PercentAttribute"},{"$ref":"#/components/schemas/DateTimeAttribute"},{"$ref":"#/components/schemas/DateAttribute"},{"$ref":"#/components/schemas/TimeAttribute"},{"$ref":"#/components/schemas/EnumAttribute"},{"$ref":"#/components/schemas/TagsAttribute"}],"discriminator":{"propertyName":"type","mapping":{"boolean":"#/components/schemas/BooleanAttribute","uuid":"#/components/schemas/UUIDAttribute","string":"#/components/schemas/StringAttribute","integer":"#/components/schemas/IntegerAttribute","float":"#/components/schemas/FloatAttribute","currency":"#/components/schemas/CurrencyAttribute","percent":"#/components/schemas/PercentAttribute","datetime":"#/components/schemas/DateTimeAttribute","date":"#/components/schemas/DateAttribute","time":"#/components/schemas/TimeAttribute","enum":"#/components/schemas/EnumAttribute","tags":"#/components/schemas/TagsAttribute"}}},"BooleanAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["boolean"],"readOnly":true},"filters":{"type":"array","items":{"$ref":"#/components/schemas/Filter"}}},"required":["field","name","type"],"additionalProperties":false},"Filter":{"type":"object","properties":{"field":{"type":"string"},"value":{"type":"string"},"op":{"type":"string","enum":["=","!=",">",">=","<","<=","in","has","contains"]}},"required":["field","op","value"],"additionalProperties":false},"UUIDAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["uuid"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"StringAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["string"],"readOnly":true},"filters":{"type":"array","items":{"$ref":"#/components/schemas/Filter"}}},"required":["field","name","type"],"additionalProperties":false},"IntegerAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["integer"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"FloatAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["float"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"CurrencyAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["currency"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"PercentAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["percent"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"DateTimeAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["datetime"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"DateAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["date"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"TimeAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["time"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"EnumAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["enum"],"readOnly":true},"filters":{"type":"array","items":{"$ref":"#/components/schemas/Filter"}}},"required":["field","name","type"],"additionalProperties":false},"TagsAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["tags"],"readOnly":true},"tags":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["field","name","type"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{}},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"status":{"type":"string"},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["error","errors","message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{}},"error":{"type":"string"},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["error","errors","message","timestamp","type"],"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## List segments

> Returns all segments for the specified provider with last-month cost, savings and coverage.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Segments (Beta)","description":"Segment management endpoints"}],"paths":{"/beta/v1/org/{org_id}/segments":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Segment"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Segments (Beta)"],"summary":"List segments","description":"Returns all segments for the specified provider with last-month cost, savings and coverage."}}},"components":{"schemas":{"Segment":{"type":"object","properties":{"delete_blockers":{"type":"array","readOnly":true,"description":"Why the segment can't be deleted. Empty when it can be.","items":{"$ref":"#/components/schemas/SegmentDeleteBlocker"}},"id":{"type":"string","description":"Unique segment identifier"},"name":{"type":"string","description":"Segment name"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"is_system_generated":{"type":"boolean","description":"True if this segment was created automatically by the system (e.g. the provider-resources default segment). Describes origin, not role — the name and filters of a system-generated segment can't change."},"description":{"type":"string","description":"Human-readable description of the segment","nullable":true},"status":{"description":"Segment status: 'new' means the segment was just created or its filters changed, and metrics data is not yet available; 'completed' means data has been populated. Metrics, cost explorer, resources, exchanges, commitment plans and plan templates accept a segment only once it is 'completed', and return 400 before then.","type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress","cancelled"]},"filters":{"readOnly":true,"description":"The segment's filter configuration, in the same format accepted by create_segment. Excludes the provider filter (already shown in the provider field)."},"monthly_budget":{"type":"number","description":"User-defined monthly spend budget for this segment, in USD. Null if no budget has been set.","nullable":true},"monthly_net_cost":{"type":"number","description":"On-demand plus commitment-covered cost of the segment's resources over the last month, in USD. 0 until status is 'completed'."},"monthly_if_all_ondemand_cost":{"type":"number","description":"What the same usage would cost at on-demand rates over the last month, in USD."},"monthly_savings":{"type":"number","description":"monthly_if_all_ondemand_cost minus monthly_net_cost: what commitments saved over the last month, in USD."},"coverage":{"type":"number","description":"Share of the segment's on-demand-equivalent cost covered by commitments, from 0 to 1."},"monthly_resource_count":{"type":"integer","description":"Number of resources the segment matched over the last month."}},"required":["delete_blockers"],"additionalProperties":false},"SegmentDeleteBlocker":{"type":"object","properties":{"code":{"type":"string","enum":["system_generated","purchase_history","auto_purchase_schedule"]},"count":{"type":"integer"},"message":{"type":"string"}},"required":["code","count","message"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{}},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"status":{"type":"string"},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["error","errors","message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{}},"error":{"type":"string"},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["error","errors","message","timestamp","type"],"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Create a new segment

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

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Segments (Beta)","description":"Segment management endpoints"}],"paths":{"/beta/v1/org/{org_id}/segments":{"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Segment"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSegmentArgs"}}}},"tags":["Segments (Beta)"],"summary":"Create a new segment","description":"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."}}},"components":{"schemas":{"Segment":{"type":"object","properties":{"delete_blockers":{"type":"array","readOnly":true,"description":"Why the segment can't be deleted. Empty when it can be.","items":{"$ref":"#/components/schemas/SegmentDeleteBlocker"}},"id":{"type":"string","description":"Unique segment identifier"},"name":{"type":"string","description":"Segment name"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"is_system_generated":{"type":"boolean","description":"True if this segment was created automatically by the system (e.g. the provider-resources default segment). Describes origin, not role — the name and filters of a system-generated segment can't change."},"description":{"type":"string","description":"Human-readable description of the segment","nullable":true},"status":{"description":"Segment status: 'new' means the segment was just created or its filters changed, and metrics data is not yet available; 'completed' means data has been populated. Metrics, cost explorer, resources, exchanges, commitment plans and plan templates accept a segment only once it is 'completed', and return 400 before then.","type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress","cancelled"]},"filters":{"readOnly":true,"description":"The segment's filter configuration, in the same format accepted by create_segment. Excludes the provider filter (already shown in the provider field)."},"monthly_budget":{"type":"number","description":"User-defined monthly spend budget for this segment, in USD. Null if no budget has been set.","nullable":true},"monthly_net_cost":{"type":"number","description":"On-demand plus commitment-covered cost of the segment's resources over the last month, in USD. 0 until status is 'completed'."},"monthly_if_all_ondemand_cost":{"type":"number","description":"What the same usage would cost at on-demand rates over the last month, in USD."},"monthly_savings":{"type":"number","description":"monthly_if_all_ondemand_cost minus monthly_net_cost: what commitments saved over the last month, in USD."},"coverage":{"type":"number","description":"Share of the segment's on-demand-equivalent cost covered by commitments, from 0 to 1."},"monthly_resource_count":{"type":"integer","description":"Number of resources the segment matched over the last month."}},"required":["delete_blockers"],"additionalProperties":false},"SegmentDeleteBlocker":{"type":"object","properties":{"code":{"type":"string","enum":["system_generated","purchase_history","auto_purchase_schedule"]},"count":{"type":"integer"},"message":{"type":"string"}},"required":["code","count","message"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{}},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"status":{"type":"string"},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["error","errors","message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{}},"error":{"type":"string"},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["error","errors","message","timestamp","type"],"additionalProperties":false},"CreateSegmentArgs":{"type":"object","properties":{"name":{"type":"string","description":"Segment name"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"filters":{"type":"object","description":"Filter tree using and/or/not combinators with field/op/value leaves. Use `has` on `tags` with nested key/value filters for tag matches. The provider filter is injected automatically.","additionalProperties":{}},"description":{"type":"string","default":null,"description":"Human-readable description","nullable":true}},"required":["filters","name","provider"],"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Get segment details

> Returns details for a single segment, with last-month cost, savings and coverage.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Segments (Beta)","description":"Segment management endpoints"}],"paths":{"/beta/v1/org/{org_id}/segments/{segment_id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Segment"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Segments (Beta)"],"summary":"Get segment details","description":"Returns details for a single segment, with last-month cost, savings and coverage."}}},"components":{"schemas":{"Segment":{"type":"object","properties":{"delete_blockers":{"type":"array","readOnly":true,"description":"Why the segment can't be deleted. Empty when it can be.","items":{"$ref":"#/components/schemas/SegmentDeleteBlocker"}},"id":{"type":"string","description":"Unique segment identifier"},"name":{"type":"string","description":"Segment name"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"is_system_generated":{"type":"boolean","description":"True if this segment was created automatically by the system (e.g. the provider-resources default segment). Describes origin, not role — the name and filters of a system-generated segment can't change."},"description":{"type":"string","description":"Human-readable description of the segment","nullable":true},"status":{"description":"Segment status: 'new' means the segment was just created or its filters changed, and metrics data is not yet available; 'completed' means data has been populated. Metrics, cost explorer, resources, exchanges, commitment plans and plan templates accept a segment only once it is 'completed', and return 400 before then.","type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress","cancelled"]},"filters":{"readOnly":true,"description":"The segment's filter configuration, in the same format accepted by create_segment. Excludes the provider filter (already shown in the provider field)."},"monthly_budget":{"type":"number","description":"User-defined monthly spend budget for this segment, in USD. Null if no budget has been set.","nullable":true},"monthly_net_cost":{"type":"number","description":"On-demand plus commitment-covered cost of the segment's resources over the last month, in USD. 0 until status is 'completed'."},"monthly_if_all_ondemand_cost":{"type":"number","description":"What the same usage would cost at on-demand rates over the last month, in USD."},"monthly_savings":{"type":"number","description":"monthly_if_all_ondemand_cost minus monthly_net_cost: what commitments saved over the last month, in USD."},"coverage":{"type":"number","description":"Share of the segment's on-demand-equivalent cost covered by commitments, from 0 to 1."},"monthly_resource_count":{"type":"integer","description":"Number of resources the segment matched over the last month."}},"required":["delete_blockers"],"additionalProperties":false},"SegmentDeleteBlocker":{"type":"object","properties":{"code":{"type":"string","enum":["system_generated","purchase_history","auto_purchase_schedule"]},"count":{"type":"integer"},"message":{"type":"string"}},"required":["code","count","message"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{}},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"status":{"type":"string"},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["error","errors","message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{}},"error":{"type":"string"},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["error","errors","message","timestamp","type"],"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Update a segment

> Changes the fields sent and keeps the rest. A filter change sets \`status\` to \`new\` until the segment's resources are recomputed. System-generated segments accept only \`description\` and \`monthly\_budget\`.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Segments (Beta)","description":"Segment management endpoints"}],"paths":{"/beta/v1/org/{org_id}/segments/{segment_id}":{"put":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Segment"}}}},"400":{"description":"`name` or `filters` was sent for a system-generated segment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"`code` is `segment_filters_locked`: the filters can't change while the segment has automatic purchases.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSegmentArgs"}}}},"tags":["Segments (Beta)"],"summary":"Update a segment","description":"Changes the fields sent and keeps the rest. A filter change sets `status` to `new` until the segment's resources are recomputed. System-generated segments accept only `description` and `monthly_budget`."}}},"components":{"schemas":{"Segment":{"type":"object","properties":{"delete_blockers":{"type":"array","readOnly":true,"description":"Why the segment can't be deleted. Empty when it can be.","items":{"$ref":"#/components/schemas/SegmentDeleteBlocker"}},"id":{"type":"string","description":"Unique segment identifier"},"name":{"type":"string","description":"Segment name"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"is_system_generated":{"type":"boolean","description":"True if this segment was created automatically by the system (e.g. the provider-resources default segment). Describes origin, not role — the name and filters of a system-generated segment can't change."},"description":{"type":"string","description":"Human-readable description of the segment","nullable":true},"status":{"description":"Segment status: 'new' means the segment was just created or its filters changed, and metrics data is not yet available; 'completed' means data has been populated. Metrics, cost explorer, resources, exchanges, commitment plans and plan templates accept a segment only once it is 'completed', and return 400 before then.","type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress","cancelled"]},"filters":{"readOnly":true,"description":"The segment's filter configuration, in the same format accepted by create_segment. Excludes the provider filter (already shown in the provider field)."},"monthly_budget":{"type":"number","description":"User-defined monthly spend budget for this segment, in USD. Null if no budget has been set.","nullable":true},"monthly_net_cost":{"type":"number","description":"On-demand plus commitment-covered cost of the segment's resources over the last month, in USD. 0 until status is 'completed'."},"monthly_if_all_ondemand_cost":{"type":"number","description":"What the same usage would cost at on-demand rates over the last month, in USD."},"monthly_savings":{"type":"number","description":"monthly_if_all_ondemand_cost minus monthly_net_cost: what commitments saved over the last month, in USD."},"coverage":{"type":"number","description":"Share of the segment's on-demand-equivalent cost covered by commitments, from 0 to 1."},"monthly_resource_count":{"type":"integer","description":"Number of resources the segment matched over the last month."}},"required":["delete_blockers"],"additionalProperties":false},"SegmentDeleteBlocker":{"type":"object","properties":{"code":{"type":"string","enum":["system_generated","purchase_history","auto_purchase_schedule"]},"count":{"type":"integer"},"message":{"type":"string"}},"required":["code","count","message"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{}},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"status":{"type":"string"},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["error","errors","message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{}},"error":{"type":"string"},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["error","errors","message","timestamp","type"],"additionalProperties":false},"UpdateSegmentArgs":{"type":"object","properties":{"name":{"type":"string","description":"Segment name. Refused on system-generated segments."},"filters":{"type":"object","description":"Filter tree in the create format. Replaces the current filters. Refused on system-generated segments, and while the segment has automatic purchases.","additionalProperties":{}},"description":{"type":"string","description":"Human-readable description. Null clears it.","nullable":true},"monthly_budget":{"type":"number","minimum":0,"description":"Monthly spend budget, in USD. Null clears it.","nullable":true}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Delete a segment

> Deletes a segment, its child segments and their draft plans. Irreversible. Refused while list and get show any \`delete\_blockers\` for the segment.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Segments (Beta)","description":"Segment management endpoints"}],"paths":{"/beta/v1/org/{org_id}/segments/{segment_id}":{"delete":{"responses":{"204":{"description":"No Content"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"The segment can't be deleted. `code` is `segment_not_deletable` and `errors.delete_blockers` lists why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Segments (Beta)"],"summary":"Delete a segment","description":"Deletes a segment, its child segments and their draft plans. Irreversible. Refused while list and get show any `delete_blockers` for the segment."}}},"components":{"schemas":{"ApiErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{}},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"status":{"type":"string"},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["error","errors","message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{}},"error":{"type":"string"},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["error","errors","message","timestamp","type"],"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.archera.ai/api-reference/beta-api/segments-beta.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
