Segments (Beta) | API & MCP Reference | Archera

Segment management endpoints

List filterable segment fields

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

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

Path parameters

org_id: string · uuid (Required)

Query parameters

provider: string · enum (Required)
- Cloud provider (aws, azure, gcp)
- Example: aws
- Possible values: aws, azure, gcp

Responses

200 OK:
- Content-Type: application/json
  - name: string (Required)
  - field: string (Required)
  - type: string · enum (Required)
    Possible values: boolean, integer, float, date, datetime, time, currency, percent, string, enum, uuid, tags
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

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

Response:

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

Get valid values for a segment filter field

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

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

Path parameters

org_id: string · uuid (Required)
field: string · min: 1 (Required)

Query parameters

provider: string · enum (Required)
- Cloud provider (aws, azure, gcp)
- Example: aws
- Possible values: aws, azure, gcp

Responses

200 OK:
- Content-Type: application/json
- object · BooleanAttribute (Optional)
- object · UUIDAttribute (Optional)
- object · StringAttribute (Optional)
- object · IntegerAttribute (Optional)
- object · FloatAttribute (Optional)
- object · CurrencyAttribute (Optional)
- object · PercentAttribute (Optional)
- object · DateTimeAttribute (Optional)
- object · DateAttribute (Optional)
- object · TimeAttribute (Optional)
- object · EnumAttribute (Optional)
- object · TagsAttribute (Optional)
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

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

Response:

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

List segments

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

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

Path parameters

org_id: string · uuid (Required)

Query parameters

provider: string · enum (Required)
- Cloud provider (aws, azure, gcp)
- Example: aws
- Possible values: aws, azure, gcp

Responses

200 OK:
- Content-Type: application/json
- id: string (Optional)
- name: string (Optional)
- provider: string · enum (Optional)
- is_system_generated: boolean (Optional)
- description: string · nullable (Optional)
- status: string · enum (Optional)
- filters: any Read-only (Optional)
- monthly_budget: number · nullable (Optional)
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

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

Response:

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

Create a new segment

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

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_id: string · uuid (Required)

Body

name: string (Required)
provider: string · enum (Required)
- Possible values: aws, azure, gcp
filters: object (Required)
- Filter tree using and/or/not combinators with field/op/value leaves.
- Use has on tags with nested key/value filters for tag matches.
description: string · nullable (Optional)
- Default: null

Responses

201 Created:
- Content-Type: application/json
- id: string (Optional)
- name: string (Optional)
- provider: string · enum (Optional)
- is_system_generated: boolean (Optional)
- description: string · nullable (Optional)
- status: string · enum (Optional)
- filters: any Read-only (Optional)
- monthly_budget: number · nullable (Optional)
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

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"
}

Response:

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

Get segment details

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

Returns details for a single segment including monthly metrics.

Path parameters

org_id: string · uuid (Required)
segment_id: string · uuid (Required)

Responses

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

Response: