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

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

Response:

``` json
[
  {
    "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

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

Response:

``` json
{
  "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

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

Response:

``` json
[
  {
    "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

``` http
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:

``` json
{
  "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

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

Response: