---
title: "Execute segment filters → companies"
method: POST
path: "/api/v1/user/segments/{id}/run"
tags: ["User"]
---

# Execute segment filters → companies

`POST /api/v1/user/segments/{id}/run`

Resolves filters_json only against the immutable corporate company_public_v2 sidecar and returns at most 500 rows. `count` is the number of rows in this bounded response, not an exact global total. Invalid/legacy filters return 400, unsupported indexed combinations return 422, and missing authority/sidecar or query failure returns 503. This mutation has no request body.

## Path parameters

- `id` integer, required

## Query parameters

- `limit` integer

## Headers

- `X-CSRF-Token` string, required

## Response `200`

Bounded result rows; count equals rows.length and is not a global total

- UserSegmentRunResponse
  - `segment_id` integer, required
  - `count` integer, required — Number of rows returned in this bounded response. It is not an exact global match count.
  - `rows` CompanySearchItem[], required
    - `slug` string, required
    - `name` string, required
    - `cif` string, required
    - `acts_count` integer, required
    - `last_seen` string, nullable
    - `province` string, nullable
    - `cnae_code` string, nullable
    - `cnae_section` string, nullable
    - `capital_cents` integer, nullable
    - `first_seen` string, nullable
    - `matched_alias` string — Present only when an exact safe alias was matched; slug is always canonical.
    - `aliases` string[]
  - `filters_applied` UserSegmentFilters, required — Corporate-only filters executed exclusively over the immutable company_public_v2 sidecar. At least one effective anchor is required: provincia, cnae_prefix, a capital bound, a year bound or recent_days. `forma` and `estado` are deliberately not accepted; stored legacy filters containing either fail closed. Without provincia/cnae_prefix, capital and temporal anchors cannot be combined; capital-only anchors accept only capital_desc/capital_asc (or the default), and temporal-only anchors accept only recent/oldest (or the default).
    - `provincia` string — Canonical Spanish province name or supported alias; matched exactly after normalization.
    - `cnae_prefix` string
    - `capital_min` integer — Euros. Must not exceed capital_max when both are present.
    - `capital_max` integer — Euros. Must be greater than or equal to capital_min when both are present.
    - `year_min` integer — Inclusive year of the first documentary record; must not exceed year_max.
    - `year_max` integer — Inclusive year of the first documentary record; must be greater than or equal to year_min.
    - `recent_days` integer — First documentary record within this rolling number of days.
    - `sort` 'capital_desc' | 'capital_asc' | 'acts_desc' | 'oldest' | 'recent' — Indexed ordering. The accepted value depends on the effective anchor as documented in x-rejected-combinations.

## Other responses

- `400` — Malformed/unknown or legally unavailable saved filter
- `401` — Authentication required (no active session)
- `403` — Invalid CSRF
- `404` — Resource not found
- `422` — Saved filters are valid individually but lack a safe indexed combination
- `503` — Canonical authority, legal layer, immutable company sidecar or bounded query unavailable

---

[API](https://skmtc.net/openmercantil/apis/openmercantil-public-api.md) · [All operations](https://skmtc.net/openmercantil/apis/openmercantil-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openmercantil/openmercantil-public-api/versions/996f96a11758/schema)