---
title: "Run Segmentation"
method: POST
path: "/data-quality/v1/segment/actions/run"
tags: ["Segment"]
---

# Run Segmentation

`POST /data-quality/v1/segment/actions/run`

## Request

- Base URL: `https://api.zoominfo.com/gtm`
- URL: `https://api.zoominfo.com/gtm/data-quality/v1/segment/actions/run`
- Auth: OAuth 2
  - Authorization code: `https://login.zoominfo.com`
  - Token URL: `https://okta-login.zoominfo.com/oauth2/default/v1/token` scopes: `api:data-quality:execute`

Sorts a batch of records into your segments and returns the assignments inline.
Synchronous: the call blocks until every record is assigned. Pass several `configIds` to
apply several dimensions in one pass.

Unknown `configIds` are skipped, not rejected. A well-formed id that matches no existing
config is silently ignored and the run proceeds on the remaining configs, so verify your ids
against List Segment Configs rather than trusting a `200` to mean every dimension was
applied.

Supply `configIds` (required, 1 to 10 segment config ids) and `records` (required, 1 to 25
records).

Returns `200` with per-record segment assignments inline. Returns `400` if `configIds` or
`records` are missing or empty, if either exceeds its limit, if a `configId` is malformed
(not a valid integer id), or if none of the supplied `configIds` match an existing config.
Returns `5xx` if the run fails before any record can be segmented; failures affecting
individual records are reported per-record in the response.

This operation consumes credits for each record segmented. Config operations are free — only
a run is billed.

## Request body

- SegmentRunRequestJsonApiModel: JSON API model for a segment run request.
  - `data` SegmentRunRequest, required: Segment run request resource.
    - `type` string, required: The type of the resource
    - `attributes` SegmentRunRequestAttributes, required: Sync segment run request attributes.
      - `configIds` string[], required: Identifiers of the segment configs to apply, in order. At least one required, up to 10.
      - `records` DataQualityRecord[], required: Input records to segment, in order. At least one required, up to 25 per request.

## Response `200`

Success

- SegmentResultsJsonApiModel: JSON API model for inline sync segment results.
  - `data` SegmentResults, required: Sync segment results resource.
    - `id` string, required: The unique identifier for the resource
    - `type` string, required: The type of the resource
    - `attributes` SegmentResultsAttributes, required: Segment results response attributes returned by the sync run endpoint.
      - `configIds` string[], required: Identifiers of the segment configs applied by this run.
      - `summary` SegmentRunSummary, required: Aggregate counts describing the outcome of a segment run.
        - `totalRecords` integer, required: Total number of records submitted in the run.
        - `successCount` integer, required: Number of records processed without error.
        - `matchedCount` integer, required: Number of records where at least one segment matched.
        - `errorCount` integer, required: Number of records that errored during segmentation.
      - `records` SegmentRecordResult[], required: Per-record segmentation outcomes, in the same order as the request's `records[]`.
        - `input` DataQualityRecord, required: A single input record, expressed as an open map of `field → value` pairs (for example `{ "industry": "Software", "country": "US" }`). The record shape is intentionally open: a config's rules reference the input fields they need *by name*. Fields a config does not reference are ignored, and a referenced field that is absent simply does not contribute — it is not an error.
        - `outputs` SegmentRecordOutput[], required: Segment outputs for each applied config, in `configIds` order.
          - `configId` string, required: Identifier of the segment config that produced this output.
          - `status` 'MATCHED' | 'UNMATCHED' | 'ERROR', required: Outcome of applying one segment config to one record.
          - `value` string: The computed output value for this record under this config: the merged output values of the segments that matched, joined using the config's `mergeOperator`. Omitted when this config produced no output — no segment matched, the record could not be evaluated, or an error occurred (see `status`).

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `429`: Too Many Requests

---

[API](https://skmtc.dev/zoominfo/apis/data-quality-api-v1.md) - [All operations](https://skmtc.dev/zoominfo/apis/data-quality-api-v1/llms.txt) - [OpenAPI document](https://skmtc.dev/zoominfo/apis/data-quality-api-v1/revisions/7229ed1f3b09?raw)