List saved segments

Your organization's saved segments for a country, with their filters as stored, and how much of the saved-segments allowance is used.

Every segment your organization saved for the country, oldest first, in one answer: a plan holds at most 1 000, so the list is not paginated. Each carries id, name, filters as stored — normalized, windows in days rather than dates — include_sole_traders, acknowledgement (null, or its version, text — the wording of that version, never edited — acknowledged_at and acknowledged_by), created_at and updated_at. Nothing is run: for the count, facets and sample, run the segment.

allowance is the organization's: used saved segments against included, the plan's figure (3 on Free, 100 on Pro, 1 000 on Scale). An organization with no saved segment answers 200 with an empty segments, not a 404.

Not counted as a call; the plan's requests per second still apply. Served for fr only; any other country is a 404. A publishable fk_pub key is refused with 403 public_key_forbidden.

GET/v1/{country_code}/segmentsScope read

Parameters

Parameter	In	Type	Required	Example
country_code	path	string	Yes	fr

Request

bash

curl -H "Authorization: Bearer $FIRMUS_KEY" \
  "https://api.firmus.sh/v1/fr/segments"

Fields

segmentsobject[]
- []objectoptional
  - idinteger
  - namestring
  - filtersobject
    - activitystring[]
      []stringoptional
  - include_sole_tradersboolean
  - acknowledgementunspecifiednullable
  - created_atstring
  - updated_atstring
allowanceobject
- includedinteger
- usedinteger

Responses

The organization's saved segments, with their filters as stored, and the plan's allowance of saved segments. Does not run them; not counted as a call.

{
  "segments": [
    {
      "id": 1,
      "name": "Software",
      "filters": {
        "activity": [
          "62"
        ]
      },
      "include_sole_traders": false,
      "acknowledgement": null,
      "created_at": "2026-11-01T09:00:00Z",
      "updated_at": "2026-11-01T09:00:00Z"
    }
  ],
  "allowance": {
    "included": 100,
    "used": 1
  }
}

Try it

Calls the real API with a demo key. No account, no signup.

country_code