Returns the results of the authenticated user's latest run of the segment for
the companies that user can access in Silverfin. This endpoint never starts a
segment run.

While a run is in progress a 202 with its progress is returned; the previous
run's results are never served as current. When no generated results exist (or
they expired), the response will return a 404 status code. You can start a new run
via POST /segments/{id}/runs.

The pending payload

While the run is in progress, the 202 response indicates current progress instead
of results:

{
  "status": "pending",
  "request_ref": "9f8c0a2e-1d3b-4f5a-8c7e-2b6d4a1f0e93",
  "started_at": "2026-08-04T09:12:44.000+02:00",
  "finished_at": null,
  "progress": {
    "processed_companies": 128
  },
  "message": "The segment run is not ready yet. Poll this endpoint until it finishes."
}

POST /segments/{id}/runs answers with this same payload (without message)
whenever it reports a pending run.

The finished payload

A finished run of a segment with two columns, one client file matching:

{
  "status": "finished",
  "request_ref": "9f8c0a2e-1d3b-4f5a-8c7e-2b6d4a1f0e93",
  "started_at": "2026-08-04T09:12:44.000+02:00",
  "finished_at": "2026-08-04T09:13:07.000+02:00",
  "period_selection": {
    "type": "financial_year",
    "date": "2025-12-31"
  },
  "columns": [
    {
      "uuid": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "type": "BookyearEnd",
      "name": "Book year end",
      "settings": {
        "comparison_mode": "exactly",
        "end_date": "2025-12-31"
      }
    },
    {
      "uuid": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
      "type": "Todos",
      "name": "To-dos",
      "settings": {
        "status": "open"
      }
    }
  ],
  "matches": [
    {
      "company_id": 918273,
      "company_name": "Acme NV",
      "period_id": 5544332,
      "period_end_date": "2025-12-31",
      "values": {
        "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d": {
          "formatted_value": "31/12/2025",
          "sort_value": "2025-12-31"
        },
        "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e": {
          "formatted_value": {
            "status": "partially_done",
            "completed": 3,
            "total": 7
          },
          "sort_value": 4
        }
      }
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 200,
    "total_matches": 128,
    "total_pages": 1
  },
  "non_match_count": 41
}

Envelope

Timestamps are ISO 8601 with the server's UTC offset (e.g. +02:00).

columns

type, name and settings are all null on the rare run column that no
longer maps to one of the segment's filters.

uuid is not an identifier, and must not be treated as stable. Its only job
is to tie a column to its values inside one response. It is stored with the run,
so fetching the same finished run again returns the same uuids, but that is a
consequence of reading one cached result twice, not a guarantee. A new run
generates new ones, and the same column then comes back under a different uuid.
So read columns from the same payload you read matches from and correlate
through it, rather than persisting a uuid or comparing uuids across responses.
columns follows the segment's filter order if you need to recognise a column
from one run to the next; type repeats when a segment has two columns of the
same kind, and name follows the run user's language.

columns.settings

Each columns item contains settings, which carries the filter's configuration
as Silverfin stores it, so you can tell what a column actually filtered on.
Its keys depend on the column's type, and it mirrors internal configuration rather
than a payload designed for the API:
treat it as informational, expect keys you do not recognise, and do not rely on
any single key being present.

Most types share a small vocabulary:

• comparison_mode: how the column matched, on all but a couple of types. One of
  equal, not_equal, less_than, greater_than, less_than_or_equal,
  greater_than_or_equal, contains, exactly, is, is not, true, false,
  up to status, from status, current-user, user, show-all, plus
  partially_starred on TemplateStarring columns. Match these
  exactly: the values are not uniformly formatted, and some carry a space or a
  hyphen rather than an underscore
• comparison_value: the value matched against, for the modes that need one
• filter_data_type: which attribute the column reads, on the types that cover
  several (CompanyData, SubmissionData)
• filter_data_value: the selected value the column matched on

Some types point at other Silverfin records, which you can resolve through the
corresponding API resources:

• firm_workflow_id: the workflow the column reports on. Absent or null
  means each client file's own default workflow (except on WorkflowUsage,
  which always names a specific workflow)
• reconciliation_text_id: the reconciliation template
• account_detail_template_id: the account detail template (TemplateStarring)
• workflow_status_id: the workflow status (WorkflowStatus)

Partner references. A segment created from a recommended (partner) template
holds firm-agnostic references, which are translated to your firm's ids before the
response is built, so you normally see the firm keys above. When your firm has
not imported the referenced template the partner reference survives instead
(partner_workflow_id, partner_reconciliation_text_id or
partner_account_detail_template_id), usually alongside a matching ..._name
key carrying the template's name so the column can still be labelled.

matches

Every entry of values carries formatted_value and sort_value (plus
filter_error when the value errored), and is null when the run holds no
value for that column:

formatted_value is display output, not data. It is built for the Silverfin
interface and translated into the profile language of the user the run belongs
to, like columns[].name; the Accept-Language header does not affect it. It
carries display formatting ("Archived - 45%", "Shared on 04/08/2026",
thousands separators). Do not parse it: its wording can change with an
interface change.
Use sort_value, or the object fields below, when you need a stable value.
Object-shaped values can gain fields in a later version, so ignore fields you
do not know.

Values by filter type

{
  "formatted_value": "31/12/2025",
  "sort_value": "2025-12-31"
}

{
  "formatted_value": "Limited company",
  "sort_value": "Limited company"
}

{
  "formatted_value": "Retail, Flanders",
  "sort_value": "Retail, Flanders"
}

{
  "formatted_value": "Marie Dubois, Jan Peeters",
  "sort_value": "Marie Dubois, Jan Peeters"
}

{
  "formatted_value": "1.284.500,00",
  "sort_value": "1284500.0"
}

{
  "formatted_value": "12.500,00",
  "sort_value": "12500.0"
}

{
  "formatted_value": "30/09/2026",
  "sort_value": "2026-09-30"
}

{
  "formatted_value": "Accepted",
  "sort_value": "accepted"
}

{
  "formatted_value": "45%",
  "sort_value": 45
}

{
  "formatted_value": "Shared on 04/08/2026",
  "sort_value": "2026-08-04T08:31:00+02:00"
}

{
  "formatted_value": "In progress",
  "sort_value": "In progress"
}

{
  "formatted_value": "Yes",
  "sort_value": "Yes"
}

A current-user FollowCompanies column resolves against the user who ran the
segment. For an API-started run, this is the token's user.

PeriodLocked shape

Always an object except for the filter_error case.

"locked"

"2026-02-14T10:22:31+01:00"

"Marie Dubois"

PreparationAndReview shapes

Branch on the key present in formatted_value.

{
  "formatted_value": {
    "no_data": true
  },
  "sort_value": null
}

{
  "formatted_value": {
    "label": "partially_prepared",
    "prepared_count": 4,
    "total_count": 9,
    "users": [
      {
        "name": "Jan Peeters",
        "user_id": 3312
      }
    ]
  },
  "sort_value": 44
}

{
  "formatted_value": {
    "label": "partially_reviewed",
    "reviewed_count": 2,
    "total_count": 8,
    "users": [
      {
        "name": "Marie Dubois",
        "user_id": 4471
      }
    ]
  },
  "sort_value": 25
}

{
  "formatted_value": {
    "preparation": {
      "name": "Jan Peeters",
      "user_id": 3312,
      "time": "2026-07-21T14:03:11.000+02:00"
    }
  },
  "sort_value": "2026-07-21T14:03:11+02:00"
}

{
  "formatted_value": {
    "preparation": null
  },
  "sort_value": null
}

{
  "formatted_value": {
    "reviews": [
      {
        "name": "Marie Dubois",
        "user_id": 4471,
        "time": "2026-07-22T08:15:40.000+02:00",
        "outdated_at": null
      }
    ]
  },
  "sort_value": "2026-07-22T08:15:40+02:00"
}

Workflow users array order is not significant.

SyncsInformation shapes

settings.scope_type selects the shape. settings.category selects the
bookkeeping or administration connection; null or absent means bookkeeping.

{
  "formatted_value": "Exact Online",
  "sort_value": "Exact Online"
}

{
  "formatted_value": "ExactOnline",
  "sort_value": "ExactOnline"
}

{
  "formatted_value": "Acme NV (ACME001)",
  "sort_value": "Acme NV (ACME001)"
}

{
  "formatted_value": {
    "status": "failed",
    "timestamp": "2026-08-03T22:05:12+02:00",
    "error_message": "An error has occurred."
  },
  "sort_value": "failed"
}

error_message is readable interface text rather than raw internals. It can
contain simple HTML markup such as <strong>.

TemplateStarring shapes

{
  "formatted_value": {
    "kind": "accounts",
    "status": "partially_starred",
    "starred_count": 2,
    "total_count": 5
  },
  "sort_value": 2
}

{
  "formatted_value": {
    "kind": "reconciliation",
    "starred": true
  },
  "sort_value": 1
}

{
  "formatted_value": "",
  "sort_value": -1
}

Todos shape

Always an object except for the filter_error case.

"partially_done"

3

7

sort_value is the number of open to-dos, total minus completed.

This endpoint exists in API v4 only; on the deprecated v3 API it returns a 404.

This endpoint requires a user OAuth token and Insights Premium.

Required scope: insights:read