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

# Segments

## List segments

> Your segments, newest first, with their status and size. GET /segments/{segmentId} returns a segment’s criteria.

```json
{"openapi":"3.1.0","info":{"title":"Goodfit Dataset API","version":"1.0.0"},"servers":[{"url":"https://api.goodfit.io"}],"security":[{"apiKey":["CLIENT_DATA_API"]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Goodfit API key, sent as the bare header value"}}},"paths":{"/dataset/segments":{"get":{"operationId":"dataset:listSegments","summary":"List segments","description":"Your segments, newest first, with their status and size. GET /segments/{segmentId} returns a segment’s criteria.","tags":["Segments"],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","description":"Rows per page, 1 to 1000","default":100,"type":"integer","minimum":1,"maximum":1000}},{"name":"iterator","in":"query","required":false,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","description":"Opaque cursor from a previous response. Omit for the first page","type":"string","minLength":1}}],"responses":{"200":{"description":"List segments","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"segments":{"type":"array","items":{"description":"A segment without its criteria","type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"},"name":{"type":"string"},"isDynamic":{"description":"A dynamic segment refreshes after every dataset sync","type":"boolean"},"status":{"description":"NEW: companies never calculated. UPDATING: recalculating companies after a criteria change. REFRESHING: recalculating companies and searching for contacts. READY: up to date. FAILED: the last calculation or refresh failed; companies from the last good run stay listed","type":"string","enum":["NEW","UPDATING","REFRESHING","READY","FAILED"]},"sizeCompanies":{"description":"Companies in the segment. Null until first calculated","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"sizeContacts":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"lastRefreshedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","isDynamic","status","sizeCompanies","sizeContacts","lastRefreshedAt","createdAt","updatedAt"],"additionalProperties":false}},"totalSegments":{"type":"integer","minimum":0,"maximum":9007199254740991},"nextIterator":{"description":"Pass as `iterator` to fetch the next page. Null on the last page","anyOf":[{"type":"string"},{"type":"null"}]},"hasMoreResults":{"type":"boolean"}},"required":["segments","totalSegments","nextIterator","hasMoreResults"],"additionalProperties":false}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["INVALID_REQUEST"]}},"required":["error","code"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["UNAUTHENTICATED"]}},"required":["error","code"],"additionalProperties":false}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["FORBIDDEN"]}},"required":["error","code"],"additionalProperties":false}}}},"429":{"description":"Too many requests","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["RATE_LIMITED"]}},"required":["error","code"],"additionalProperties":false}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["INTERNAL_ERROR"]}},"required":["error","code"],"additionalProperties":false}}}}}}}}}
```

## Create a segment

> Saves a segment and starts calculating its companies, which runs in the background: the segment comes back UPDATING, so poll GET /segments/{segmentId} until it is READY. Spends no credits.

```json
{"openapi":"3.1.0","info":{"title":"Goodfit Dataset API","version":"1.0.0"},"servers":[{"url":"https://api.goodfit.io"}],"security":[{"apiKey":["CLIENT_DATA_API"]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Goodfit API key, sent as the bare header value"}}},"paths":{"/dataset/segments":{"post":{"operationId":"dataset:createSegment","summary":"Create a segment","description":"Saves a segment and starts calculating its companies, which runs in the background: the segment comes back UPDATING, so poll GET /segments/{segmentId} until it is READY. Spends no credits.","tags":["Segments"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"filters":{"description":"Filter group over your dataset’s data points, in the same format as company search. List the data points first (dataset_list_company_fields, or GET /companies/fields)","type":"object","properties":{},"additionalProperties":{}},"excludeDomains":{"description":"Companies left out whatever the filters say","default":[],"maxItems":10000,"type":"array","items":{"type":"string","minLength":1,"maxLength":253}},"companyLimit":{"default":null,"anyOf":[{"description":"Caps the segment at a number of companies, keeping the first by orderBy","type":"object","properties":{"max":{"description":"At most this many companies are included","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"orderBy":{"description":"fieldName of the data point that decides which companies stay","type":"string","minLength":1},"orderDirection":{"type":"string","enum":["ASC","DESC"]}},"required":["max"]},{"type":"null"}]},"name":{"description":"Unique among your segments","type":"string","minLength":1,"maxLength":255},"isDynamic":{"description":"Refresh after every dataset sync","default":false,"type":"boolean"}},"required":["filters","name"]}}}},"responses":{"202":{"description":"Saved; calculating","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"segment":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"},"name":{"type":"string"},"isDynamic":{"description":"A dynamic segment refreshes after every dataset sync","type":"boolean"},"status":{"description":"NEW: companies never calculated. UPDATING: recalculating companies after a criteria change. REFRESHING: recalculating companies and searching for contacts. READY: up to date. FAILED: the last calculation or refresh failed; companies from the last good run stay listed","type":"string","enum":["NEW","UPDATING","REFRESHING","READY","FAILED"]},"sizeCompanies":{"description":"Companies in the segment. Null until first calculated","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"sizeContacts":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"lastRefreshedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"filters":{},"excludeDomains":{"type":"array","items":{"type":"string"}},"companyLimit":{"anyOf":[{"description":"Caps the segment at a number of companies, keeping the first by orderBy","type":"object","properties":{"max":{"description":"At most this many companies are included","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"orderBy":{"description":"fieldName of the data point that decides which companies stay","type":"string","minLength":1},"orderDirection":{"type":"string","enum":["ASC","DESC"]}},"required":["max"],"additionalProperties":false},{"type":"null"}]}},"required":["id","name","isDynamic","status","sizeCompanies","sizeContacts","lastRefreshedAt","createdAt","updatedAt","filters","excludeDomains","companyLimit"],"additionalProperties":false}},"required":["segment"],"additionalProperties":false}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["INVALID_REQUEST"]}},"required":["error","code"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["UNAUTHENTICATED"]}},"required":["error","code"],"additionalProperties":false}}}},"403":{"description":"The account has reached its segment limit","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["FORBIDDEN"]}},"required":["error","code"],"additionalProperties":false}}}},"409":{"description":"A live segment already has this name","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["CONFLICT"]}},"required":["error","code"],"additionalProperties":false}}}},"429":{"description":"Too many requests","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["RATE_LIMITED"]}},"required":["error","code"],"additionalProperties":false}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["INTERNAL_ERROR"]}},"required":["error","code"],"additionalProperties":false}}}}}}}}}
```

## Get a segment

> One segment: its criteria, status and size. Poll this after a change until status is READY.

```json
{"openapi":"3.1.0","info":{"title":"Goodfit Dataset API","version":"1.0.0"},"servers":[{"url":"https://api.goodfit.io"}],"security":[{"apiKey":["CLIENT_DATA_API"]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Goodfit API key, sent as the bare header value"}}},"paths":{"/dataset/segments/{segmentId}":{"get":{"operationId":"dataset:getSegment","summary":"Get a segment","description":"One segment: its criteria, status and size. Poll this after a change until status is READY.","tags":["Segments"],"parameters":[{"name":"segmentId","in":"path","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","description":"The segment id","type":"string"}}],"responses":{"200":{"description":"Get a segment","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"segment":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"},"name":{"type":"string"},"isDynamic":{"description":"A dynamic segment refreshes after every dataset sync","type":"boolean"},"status":{"description":"NEW: companies never calculated. UPDATING: recalculating companies after a criteria change. REFRESHING: recalculating companies and searching for contacts. READY: up to date. FAILED: the last calculation or refresh failed; companies from the last good run stay listed","type":"string","enum":["NEW","UPDATING","REFRESHING","READY","FAILED"]},"sizeCompanies":{"description":"Companies in the segment. Null until first calculated","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"sizeContacts":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"lastRefreshedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"filters":{},"excludeDomains":{"type":"array","items":{"type":"string"}},"companyLimit":{"anyOf":[{"description":"Caps the segment at a number of companies, keeping the first by orderBy","type":"object","properties":{"max":{"description":"At most this many companies are included","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"orderBy":{"description":"fieldName of the data point that decides which companies stay","type":"string","minLength":1},"orderDirection":{"type":"string","enum":["ASC","DESC"]}},"required":["max"],"additionalProperties":false},{"type":"null"}]}},"required":["id","name","isDynamic","status","sizeCompanies","sizeContacts","lastRefreshedAt","createdAt","updatedAt","filters","excludeDomains","companyLimit"],"additionalProperties":false}},"required":["segment"],"additionalProperties":false}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["INVALID_REQUEST"]}},"required":["error","code"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["UNAUTHENTICATED"]}},"required":["error","code"],"additionalProperties":false}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["FORBIDDEN"]}},"required":["error","code"],"additionalProperties":false}}}},"404":{"description":"No segment with this id exists for your account","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["NOT_FOUND"]}},"required":["error","code"],"additionalProperties":false}}}},"429":{"description":"Too many requests","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["RATE_LIMITED"]}},"required":["error","code"],"additionalProperties":false}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["INTERNAL_ERROR"]}},"required":["error","code"],"additionalProperties":false}}}}}}}}}
```

## Delete a segment

> Deletes the segment and, in the background, removes its companies and contacts from it. The contacts stay granted to your account and keep appearing in GET /contacts.

```json
{"openapi":"3.1.0","info":{"title":"Goodfit Dataset API","version":"1.0.0"},"servers":[{"url":"https://api.goodfit.io"}],"security":[{"apiKey":["CLIENT_DATA_API"]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Goodfit API key, sent as the bare header value"}}},"paths":{"/dataset/segments/{segmentId}":{"delete":{"operationId":"dataset:deleteSegment","summary":"Delete a segment","description":"Deletes the segment and, in the background, removes its companies and contacts from it. The contacts stay granted to your account and keep appearing in GET /contacts.","tags":["Segments"],"parameters":[{"name":"segmentId","in":"path","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","description":"The segment id","type":"string"}}],"responses":{"204":{"description":"Deleted; no body"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["INVALID_REQUEST"]}},"required":["error","code"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["UNAUTHENTICATED"]}},"required":["error","code"],"additionalProperties":false}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["FORBIDDEN"]}},"required":["error","code"],"additionalProperties":false}}}},"404":{"description":"No segment with this id exists for your account","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["NOT_FOUND"]}},"required":["error","code"],"additionalProperties":false}}}},"409":{"description":"The segment is updating or refreshing","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["CONFLICT"]}},"required":["error","code"],"additionalProperties":false}}}},"429":{"description":"Too many requests","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["RATE_LIMITED"]}},"required":["error","code"],"additionalProperties":false}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["INTERNAL_ERROR"]}},"required":["error","code"],"additionalProperties":false}}}}}}}}}
```

## Update a segment

> Changes only the fields sent. New criteria recalculate the companies in the background (202): poll GET /segments/{segmentId} until it is READY. A name or isDynamic change alone saves straight away (200). A dynamic segment with personas searches for contacts after every dataset sync, spending contact credits.

```json
{"openapi":"3.1.0","info":{"title":"Goodfit Dataset API","version":"1.0.0"},"servers":[{"url":"https://api.goodfit.io"}],"security":[{"apiKey":["CLIENT_DATA_API"]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Goodfit API key, sent as the bare header value"}}},"paths":{"/dataset/segments/{segmentId}":{"patch":{"operationId":"dataset:updateSegment","summary":"Update a segment","description":"Changes only the fields sent. New criteria recalculate the companies in the background (202): poll GET /segments/{segmentId} until it is READY. A name or isDynamic change alone saves straight away (200). A dynamic segment with personas searches for contacts after every dataset sync, spending contact credits.","tags":["Segments"],"parameters":[{"name":"segmentId","in":"path","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","description":"The segment id","type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"isDynamic":{"description":"A dynamic segment refreshes after every dataset sync","type":"boolean"},"filters":{"description":"Filter group over your dataset’s data points, in the same format as company search. List the data points first (dataset_list_company_fields, or GET /companies/fields)","type":"object","properties":{},"additionalProperties":{}},"excludeDomains":{"maxItems":10000,"type":"array","items":{"type":"string","minLength":1,"maxLength":253}},"companyLimit":{"anyOf":[{"description":"Caps the segment at a number of companies, keeping the first by orderBy","type":"object","properties":{"max":{"description":"At most this many companies are included","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"orderBy":{"description":"fieldName of the data point that decides which companies stay","type":"string","minLength":1},"orderDirection":{"type":"string","enum":["ASC","DESC"]}},"required":["max"]},{"type":"null"}]}}}}}},"responses":{"200":{"description":"Update a segment","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"segment":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"},"name":{"type":"string"},"isDynamic":{"description":"A dynamic segment refreshes after every dataset sync","type":"boolean"},"status":{"description":"NEW: companies never calculated. UPDATING: recalculating companies after a criteria change. REFRESHING: recalculating companies and searching for contacts. READY: up to date. FAILED: the last calculation or refresh failed; companies from the last good run stay listed","type":"string","enum":["NEW","UPDATING","REFRESHING","READY","FAILED"]},"sizeCompanies":{"description":"Companies in the segment. Null until first calculated","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"sizeContacts":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"lastRefreshedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"filters":{},"excludeDomains":{"type":"array","items":{"type":"string"}},"companyLimit":{"anyOf":[{"description":"Caps the segment at a number of companies, keeping the first by orderBy","type":"object","properties":{"max":{"description":"At most this many companies are included","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"orderBy":{"description":"fieldName of the data point that decides which companies stay","type":"string","minLength":1},"orderDirection":{"type":"string","enum":["ASC","DESC"]}},"required":["max"],"additionalProperties":false},{"type":"null"}]}},"required":["id","name","isDynamic","status","sizeCompanies","sizeContacts","lastRefreshedAt","createdAt","updatedAt","filters","excludeDomains","companyLimit"],"additionalProperties":false}},"required":["segment"],"additionalProperties":false}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["INVALID_REQUEST"]}},"required":["error","code"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["UNAUTHENTICATED"]}},"required":["error","code"],"additionalProperties":false}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["FORBIDDEN"]}},"required":["error","code"],"additionalProperties":false}}}},"404":{"description":"No segment with this id exists for your account","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["NOT_FOUND"]}},"required":["error","code"],"additionalProperties":false}}}},"409":{"description":"The segment is updating or refreshing, or another live segment has this name","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["CONFLICT"]}},"required":["error","code"],"additionalProperties":false}}}},"429":{"description":"Too many requests","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["RATE_LIMITED"]}},"required":["error","code"],"additionalProperties":false}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["INTERNAL_ERROR"]}},"required":["error","code"],"additionalProperties":false}}}}}}}}}
```

## Preview a segment

> How many companies a segment with these criteria would hold, without saving it. \`sample\` returns up to that many of those companies too.

```json
{"openapi":"3.1.0","info":{"title":"Goodfit Dataset API","version":"1.0.0"},"servers":[{"url":"https://api.goodfit.io"}],"security":[{"apiKey":["CLIENT_DATA_API"]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Goodfit API key, sent as the bare header value"}}},"paths":{"/dataset/segments/preview":{"post":{"operationId":"dataset:previewSegment","summary":"Preview a segment","description":"How many companies a segment with these criteria would hold, without saving it. `sample` returns up to that many of those companies too.","tags":["Segments"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"filters":{"description":"Filter group over your dataset’s data points, in the same format as company search. List the data points first (dataset_list_company_fields, or GET /companies/fields)","type":"object","properties":{},"additionalProperties":{}},"excludeDomains":{"description":"Companies left out whatever the filters say","default":[],"maxItems":10000,"type":"array","items":{"type":"string","minLength":1,"maxLength":253}},"companyLimit":{"default":null,"anyOf":[{"description":"Caps the segment at a number of companies, keeping the first by orderBy","type":"object","properties":{"max":{"description":"At most this many companies are included","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"orderBy":{"description":"fieldName of the data point that decides which companies stay","type":"string","minLength":1},"orderDirection":{"type":"string","enum":["ASC","DESC"]}},"required":["max"]},{"type":"null"}]},"sample":{"description":"Companies to return, 0 to 50","default":0,"type":"integer","minimum":0,"maximum":50}},"required":["filters"]}}}},"responses":{"200":{"description":"Preview a segment","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"sizeCompanies":{"type":"integer","minimum":0,"maximum":9007199254740991},"companies":{"description":"Identifying data points only","type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}}},"required":["sizeCompanies","companies"],"additionalProperties":false}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["INVALID_REQUEST"]}},"required":["error","code"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["UNAUTHENTICATED"]}},"required":["error","code"],"additionalProperties":false}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["FORBIDDEN"]}},"required":["error","code"],"additionalProperties":false}}}},"429":{"description":"Too many requests","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["RATE_LIMITED"]}},"required":["error","code"],"additionalProperties":false}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["INTERNAL_ERROR"]}},"required":["error","code"],"additionalProperties":false}}}}}}}}}
```

## Refresh a segment

> Recalculates the companies and searches again for contacts for each persona on the segment, in the background (202): poll GET /segments/{segmentId} until it is READY. Each contact newly granted to your account costs one contact credit. A segment never calculated, or whose last calculation failed, is recalculated instead, which spends nothing.

```json
{"openapi":"3.1.0","info":{"title":"Goodfit Dataset API","version":"1.0.0"},"servers":[{"url":"https://api.goodfit.io"}],"security":[{"apiKey":["CLIENT_DATA_API"]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Goodfit API key, sent as the bare header value"}}},"paths":{"/dataset/segments/{segmentId}/refresh":{"post":{"operationId":"dataset:refreshSegment","summary":"Refresh a segment","description":"Recalculates the companies and searches again for contacts for each persona on the segment, in the background (202): poll GET /segments/{segmentId} until it is READY. Each contact newly granted to your account costs one contact credit. A segment never calculated, or whose last calculation failed, is recalculated instead, which spends nothing.","tags":["Segments"],"parameters":[{"name":"segmentId","in":"path","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","description":"The segment id","type":"string"}}],"responses":{"202":{"description":"Refreshing","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"segment":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"},"name":{"type":"string"},"isDynamic":{"description":"A dynamic segment refreshes after every dataset sync","type":"boolean"},"status":{"description":"NEW: companies never calculated. UPDATING: recalculating companies after a criteria change. REFRESHING: recalculating companies and searching for contacts. READY: up to date. FAILED: the last calculation or refresh failed; companies from the last good run stay listed","type":"string","enum":["NEW","UPDATING","REFRESHING","READY","FAILED"]},"sizeCompanies":{"description":"Companies in the segment. Null until first calculated","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"sizeContacts":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"lastRefreshedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"filters":{},"excludeDomains":{"type":"array","items":{"type":"string"}},"companyLimit":{"anyOf":[{"description":"Caps the segment at a number of companies, keeping the first by orderBy","type":"object","properties":{"max":{"description":"At most this many companies are included","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"orderBy":{"description":"fieldName of the data point that decides which companies stay","type":"string","minLength":1},"orderDirection":{"type":"string","enum":["ASC","DESC"]}},"required":["max"],"additionalProperties":false},{"type":"null"}]}},"required":["id","name","isDynamic","status","sizeCompanies","sizeContacts","lastRefreshedAt","createdAt","updatedAt","filters","excludeDomains","companyLimit"],"additionalProperties":false}},"required":["segment"],"additionalProperties":false}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["INVALID_REQUEST"]}},"required":["error","code"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["UNAUTHENTICATED"]}},"required":["error","code"],"additionalProperties":false}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["FORBIDDEN"]}},"required":["error","code"],"additionalProperties":false}}}},"404":{"description":"No segment with this id exists for your account","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["NOT_FOUND"]}},"required":["error","code"],"additionalProperties":false}}}},"409":{"description":"The segment is already updating or refreshing","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["CONFLICT"]}},"required":["error","code"],"additionalProperties":false}}}},"429":{"description":"Too many requests","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["RATE_LIMITED"]}},"required":["error","code"],"additionalProperties":false}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human readable. Wording may change between releases","type":"string"},"code":{"description":"Stable identifier. Match on this rather than on `error`","type":"string","enum":["INTERNAL_ERROR"]}},"required":["error","code"],"additionalProperties":false}}}}}}}}}
```