Read a job

Polling

The same id answers for an analysis started by POST /v1/analyze and for a follow-up run by POST /v1/action.

While the job is running the response carries status, a numeric stage, a stageKey and a human-readable stageName. Branch on status, which is QUEUED, IN_PROGRESS, COMPLETED or FAILED.

stageKey is the one to show your users. It names the stage, so you can write the line in your own reader's language rather than receive ours. The two flows do not share a vocabulary, and the follow-up flow is not the analysis flow with a different prefix — there is no action-reviewing and no action-consolidating. These fifteen keys are the whole set:

• An analysis reports analysis-queued, analysis-preparing, analysis-reviewing, analysis-consolidating, analysis-complete. A run on a demonstration profile answers from a prepared example instead of calling a model, and reports analysis-demo-skipping-ai and analysis-demo-finalising where an ordinary run reports the reviewing and consolidating stages.
• A follow-up document reports action-queued, action-preparing, action-drafting, action-complete, action-document-ready. An outline-only run shares action-preparing with the full run and reports action-skeleton-queued, action-skeleton-complete and action-skeleton-document-ready in place of the three that name a written document.

Keys are added as the pipeline gains stages; a key you do not recognise means "no wording for this one yet", not an error, so fall back to something generic rather than showing the raw key. A job created before this field existed does not carry one.

stageName is the same information as a Swedish sentence, and it is prose rather than contract: it is written for a person and changes without notice. It stays for clients that already read it.

Poll every few seconds. Reading a job spends no quota, so polling costs nothing but requests. A job that reaches FAILED carries errorMessage, written for a person, and errorCategory, written for your code to branch on. Two categories are worth handling on their own. INVALID_CONFIGURATION means the profile the run needed no longer resolves — most often because it was edited after the analysis was queued. Retrying the same document changes nothing until the profile is fixed. DELIVERY_WINDOW_EXHAUSTED means the run ran out of the thirty minutes every run has — a retry was refused because too little of the window was left to deliver in. Nothing was delivered and the run was not charged, and a new analysis of the same document is the right answer, because it gets the whole window again. Every other category is ours, not yours.

A webhook removes the need to poll at all; you still fetch the result from here when it arrives.

The finished result

At COMPLETED the response gains a result object, and what is inside it depends on which call created the job:

• an analysis puts the audit in result.clinicalData — the summary, the findings, and the legal provision each finding is anchored in;
• an action puts its output in result.generatedDocument.

Sending includeTrace=true on this call adds result.analysisTrace to a finished analysis: which legal sources each reviewer was given. It is off unless you ask — see the legal trace, on request below.

Asking for includeDiagnostics on the original call adds result.diagnostics: each reviewer's individual output and every consolidating step's output for an analysis, the generator's own metadata for an action. It works in every environment, production included, and it makes the response considerably larger.

An analysis answers with two fields there. workers is an array with one entry per reviewer call, each carrying workerId, the profileId of the review it ran in, workerName and the reviewer's raw output. reducers is the consolidation half: an object with one entry per review, keyed by that review's profileId, each holding the consolidated output and its tokens. An ordinary run has exactly one entry; a run started with a review package has one per member, because each review is consolidated on its own and neither is the whole answer.

reducer, singular, is deprecated. It is still published and still holds exactly what it always did for an ordinary run — the same record reducers now carries under that run's profileId — so nothing you read today has changed. It is null for a review package: there are two consolidations and the field can only hold one, so it holds neither rather than passing off half the answer as the whole. Read reducers and key it by the profile you care about. No removal date is set; we will tell you before one is.

Both fields are keyed by the resolved profile id — the same string a finding's profile_id carries, prefixed as described under Which review found a finding — so a finding and the consolidation that produced it can be matched without any string surgery. workerId is likewise the reviewer's own id: the review it belongs to is the profileId beside it, never a prefix inside the id itself.

A finding's legal citation carries a source_key for an authored source and a typed reference for a provision of published law. Both are looked up through GET /v1/snippets, which is what makes a citation in a report clickable.

Every field of the analysis result

result.clinicalData carries these ten fields and no others. The list is the contract: a field inside the engine that is not named here is not sent, and one that is added here is announced before it ships.

Nine of the ten are on every finished analysis. The tenth, profile_executive_summaries, is sent only when the run used a review package — see A review package answers with one classification per review below.

• identified_document_type — what the analysis classified the document as, in the output language. null when it could not tell. A string for an ordinary run, and a list of strings when the profileId you sent names a review package — see A review package answers with one classification per review below.
• document_year — the year of the audited document. Always null on this release; the engine does not extract it yet, and the field is published because it is delivered, not because it is useful.
• used_rules — every legal source the run assembled, keyed by the id a citation's source_key names. Each value is the whole stored source record, text included, so this is by far the largest field in the response. Read a citation's source from here rather than fetching it again.
• internal_reasoning — the consolidating step's own working notes: how it classified the document, which reviewer findings it judged to be the same finding, and how it planned the summary. Written for the model rather than for a reader.
• detected_language — the language the text fields were actually written in, reported by the model itself. Normally the profile's output language; worth checking if you render into a language-specific view.
• executive_summary — an objective, quantitative summary of the audit. On a review package it is every review's summary in member order, separated by a blank line.
• profile_executive_summaries — the same summaries told apart: { profile_id, executive_summary }, one entry per review that wrote a summary, in the package's member order. Sent only for a run that used a review package, and absent — not empty — for every other run. Pair an entry with a review through its profile_id and never through its position: the list can be shorter than the number of reviews. See A review package answers with one classification per review below.
• is_flawless — true only when deduplicated_flaws is empty.
• deduplicated_flaws — the findings, merged across reviewers.
• consolidated_strengths — what the document did correctly, in the same shape.

A flaw carries page_reference and exact_quote (both nullable — an omission has nothing to quote), context_description and quoted_locator, a flaw_title, a description, is_omission, regulatory_references, finding_id, profile_id, source_flaw_ids — the ids of the individual reviewer findings that were merged into it, which is what makes a consolidated finding traceable back through result.diagnostics — and fenced_verbatim. A strength is the same minus is_omission, context_description, quoted_locator, finding_id, profile_id and source_flaw_ids, with strength_title in place of flaw_title. It keeps page_reference, exact_quote and fenced_verbatim.

context_description is where in the document to look — "Under the heading The Child's Views", "In the signature block" — carried over from the reviewer finding that reported it rather than composed at consolidation. It is nullable, but it is the field to render for a finding whose exact_quote is null: an omission is the statement that something is absent, so it has nothing to quote and this locator is all a reader has to find the place.

Every analysis run since the field shipped carries it on every flaw, quoted or not. Treat the key itself as optional all the same: an analysis that finished just before that release and is fetched just after it is delivered without it, because we send what the stored result holds rather than padding it out. Read a missing key the same way you read null — no locator was recorded — and not as a flaw whose place is unknown.

quoted_locator is the heading context_description names, on its own: "The Child's Views" where the prose reads "Under the heading The Child's Views". It is the same string, reproduced character-for-character from the document, and it is there so you can tell which bytes of the locator are the document's and which are ours — see which words are the document's below. It is null when the place carries no heading at all, and the key is optional for the same reason context_description's is. Render context_description; quoted_locator is for a program.

A citation in regulatory_references names the binding source and, optionally, the supporting one: primary_binding_source and primary_authority_type with primary_label, and the supporting_* trio which is null when the finding rests on statute alone. primary_source and supporting_source are what those labels resolved to — { label, source_key, reference, authorityType }, where reference is a typed { jurisdiction, work, pinpoint } for a provision of published law and null for an authored source. Either resolution is null when the model cited a label the run never issued; the engine reports that rather than inventing a source, and so do we. A resolution of a source imported from a source document also carries importProvenance: { derivation, sourceTitle, sourceUrl?, sourceVersion?, supportSpans }, read off our record and never off the model. derivation is "verbatim" when the source's text is the document's exact wording, and "accepted_summary" when it is a summary an administrator accepted. Show that difference: a summary is not a quotation, even where it binds. supportSpans are half-open [start, end) UTF-16 offsets into the document's extracted text, which we do not keep. The field is absent on every other source.

Four older names on a citation — primary_norm_level, primary_id, supporting_norm_level and supporting_id — are no longer sent. Read their successors.

exact_quote is in the document's own language, never translated, so that you can find it in the source by searching for it. context_description is a third case, translated in part: its framing prose follows the output language, while a heading, section label or form-field name named inside it is reproduced character-for-character from the document — for the same reason, since a translated heading is a locator pointing at nothing. Every other text field follows the profile's output language throughout.

Which review found a finding, and which finding it is

Every flaw carries two ids the engine mints for it. Neither comes from a model, and both are on every response — a run under a single profile included, so you never have to branch on whether the key is there.

• profile_id names the review that produced the finding: the stored id of the analysis profile the run used.
• finding_id identifies the finding within the response. It reads <profile_id>:<n>, numbered from 1 within each review.

Both are stable within one response and nowhere else. Re-running the same document is a second set of model answers in a different order, and the same finding_id will not name the same finding. Store them alongside a response you keep; do not treat one as a durable handle on a finding.

Group findings by profile_id; never parse finding_id. A profile id is a stored record id and may itself contain a colon, so the separator marks the boundary without proving where it is. The two fields carry the same string for the same review, so grouping needs no parsing at all.

profile_id is not necessarily the profileId you sent. You send the id the profile is published under — lss_utredning — and the response names the record that answered it, which for a profile from our own catalogue is SYSTEM_lss_utredning and for your organisation's own fork carries your workspace's prefix instead. Treat it as opaque, compare findings against each other rather than against what you sent, and read the prefix as whose copy of the profile ran if you want it.

A review package answers with one classification per review

A review package is one profileId that names several profiles, and a job started with one runs each of them over the same document. The reviews are kept apart on purpose: findings are never merged across them, because two angles reaching the same conclusion is an agreement worth seeing rather than a duplicate to collapse. deduplicated_flaws therefore carries every review's findings, in the package's own member order, told apart by profile_id.

One field changes shape with it. identified_document_type is a list when the run used a package — one entry per review, in the same member order — because each profile classifies the document from its own angle and there is no single answer to give. For every other run it is the string it has always been, so a client that sends an ordinary profileId sees nothing new here.

If you accept both, read the field as "a string or an array of strings" rather than testing for an array: [].concat(identified_document_type ?? []) gives you the list in either case.

One field appears with it. profile_executive_summaries is sent only for a package run: an array of { profile_id, executive_summary }, in the same member order, each carrying the same profile_id its findings carry. Each review writes its own summary counting only its own findings, which is what makes two of them safe to place side by side and wrong to add up.

executive_summary is those same summaries joined with a blank line, and it is unchanged on both kinds of run — it stays the whole summary for a client that reads only it. Use the split field rather than taking the joined string apart: a summary is free prose and may contain a blank line of its own, so splitting it is a guess rather than a reading. That is the whole reason the field exists.

Pair the entries by profile_id, never by position. The list carries one entry per review that wrote a summary, and a review can finish without writing one: when the step that merges a review's findings into a summary fails, that review still delivers its findings — they carry its profile_id like any others — and contributes no summary. So a two-review package can answer with one entry, or with none, while identified_document_type still has two and the findings still carry both ids. Nothing else in the response marks which review it was; matching the two lists off against each other by index is what puts the wrong label on a summary.

executive_summary follows the list exactly: it is the entries you were sent, joined with a blank line, and nothing else. When the list is short the joined string is short with it, and when the list is empty the joined string is empty too — so the two never disagree about which reviews said something.

The key is absent, not empty, for a run that did not use a package — every ordinary run, which is to say every run most integrations ever make. There is no angle to attribute a summary to when only one review ran, and a list of one would have you draw a label nobody needs. Read a missing key as "this response has one summary and it is in executive_summary". An empty array means something different and only ever arrives on a package run: the reviews ran, and none of their summaries survived.

Diagnostics follow the same principle. A package's result.diagnostics.reducers carries one entry per review rather than one for the run, and its deprecated reducer is null — see The finished result above.

The legal trace, on request

Add ?includeTrace=true to this call and a finished analysis also answers result.analysisTrace: for this run, each review as it was resolved, every reviewer whose answer was included, and the legal sources each of them was supplied, beside the sources the report cited. It sits next to result.clinicalData, not inside it, and the ten fields above are unchanged.

Only the literal true turns it on. Leave the parameter out, or send false, and the response is exactly what it is without this feature, even though the run has a trace. Any other value — 1, TRUE, an empty value — or the parameter sent twice answers 400 BAD_REQUEST, so a client that meant to ask never silently gets nothing. The check comes after the job is found and shown to be yours, so a 404 or 403 comes first.

It is for an analysis only. A follow-up document started by POST /v1/action carries no trace: the parameter is accepted there and adds no key at all. A job that is QUEUED, IN_PROGRESS or FAILED has no result, so it has no trace either.

An absent key and null say different things. An absent analysisTrace means you did not ask. null means you asked and this run has no trace we can vouch for: a run that finished before the trace existed, or a stored trace that does not pass validation. We answer null rather than an empty trace, because an empty list of sources would claim that no source was supplied.

Supplied means given to the reviewer, not relied upon. A reviewer's suppliedSourceIds records the sources that were given to that reviewer, loaded into what it was shown. lanes[].citedSourceIds records the sources a lane's findings cite that were supplied to that lane's reviewers, and strengthCitedSourceIds the sources in the run-wide sources list that the strengths cite. Neither says what the reasoning behind an assessment relied on: a supplied source may have gone unused, and a citation records what the report points to, not what the reasoning rested on.

The two lists of unmatched citations have different scopes.

• lanes[].unverifiedCitationKeys belongs to one lane: citations in that lane's findings whose source is not among the sources supplied to that lane's reviewers — every suppliedSourceIds of its workers together. In a review package such a key can be a source that was supplied only to another review of the same run, as snip_lvu_2 is below.
• strengthUnverifiedCitationKeys is report-level, because strengths are not tied to a review: strength citations whose source is not in the run-wide sources list, which holds every source supplied to any reviewer in the run.

A citation the model invented never reaches either list; it stays unresolved in the finding itself.

It is ids and labels, never text. A source carries its id (the value a citation's source_key holds), snippetKey, name, authorityType and a reference that is null for an authored source. No legal text, no prompt and none of the document's words are in the trace, which is why textProvenance lists no path inside it. Look a source's text up through GET /v1/snippets if you need it.

The trace is stored with the result and removed with it: the same retention window applies, and asking for it does not extend it. contractVersion stays 1; this is an added field.

The response says which contract it follows

Every answer from this endpoint carries contractVersion, currently 1, alongside jobId — on a queued job as well as a finished one, so you can branch on it before there is a result to read.

It changes when a published field is removed, renamed, or changes meaning, and we tell you before that happens. It does not change when a field is added: a client that does not read a new field cannot be broken by one, so treat unknown fields as ignorable rather than as an error.

That is the promise this version number exists to make good on. Before it, the response was assembled from whatever the engine happened to store, which meant an internal rename could reach you unannounced in an ordinary deploy. It is now built from one published list — the ten fields above — and nothing else can leave the boundary.

Which words are the document's

The document you sent us is text somebody else wrote, and an audit report quotes it. If you feed this response to a language model — your own assistant, a summariser, an agent that drafts a reply — a sentence inside the audited document can otherwise be read as an instruction to that model rather than as material it is being shown. Nothing here is leaked and nothing about your account is at risk; what was missing was a boundary between what we say and what the document says. Every answer that carries a result now states one, in two forms.

textProvenance on the envelope says where the document's words are in this particular answer. verbatim lists the paths whose value is text from the document; mayContainVerbatim lists the fields that are ours but may reproduce fragments of it — the consolidating step's internal_reasoning above all, and result.generatedDocument for a follow-up document. Paths are written from the response root with [] for "every element of this array" and {} for "every value of this object, whatever its keys are", e.g. result.clinicalData.deduplicated_flaws[].exact_quote and result.diagnostics.reducers{}.output.internal_reasoning. Diagnostics paths appear only when you asked for diagnostics — and if you did, note that the answer carries the document's words more than once: each consolidating step's own record under result.diagnostics.reducers{}.output is the finished audit a second time, unfenced, and the deprecated result.diagnostics.reducer.output is that record once more for an ordinary run. Every path in them is listed too. Treat everything in both lists as data, never as instruction.

fenced_verbatim on each finding says the same thing in the bytes, for a reader that serialises the response rather than parsing it: the finding's quote, and its quoted_locator where there is one, wrapped in a tag whose name ends in a random nonce that is minted per response and published as textProvenance.nonce. The nonce is the point — a fixed delimiter could be closed by a sentence written into the audited document, and a random one cannot be written in advance by anyone who has not seen the answer. A finding with nothing verbatim to fence carries no such key.

Two consequences worth coding for. The nonce differs between two reads of the same job, so fenced_verbatim differs too while exact_quote does not — exclude the fenced fields if you byte-compare two responses. And the fence is a marking, never an edit: exact_quote is still the document's text character-for-character, so it still matches the source when you search for it.

contractVersion stays 1. These are added fields; nothing you read today changed meaning.

The result has minutes to live

Reading a job does not destroy it: within the window this call is repeatable and answers the same result each time.

What destroys it is the retention sweep, which is scheduled every four minutes. It looks for jobs that have not changed in the last fifteen minutes and deletes each job, stored result and source file that a successful run reaches. Normally, a finished analysis is removed between fifteen and thirty minutes after its last change, read or unread, when cleanup succeeds and reaches that job within its per-run capacity. The thirty-minute window allows two missed sweep runs and the sweep's execution only when the next run succeeds and reaches the job. Further failed runs or a backlog beyond that run's capacity can delay deletion beyond thirty minutes; the job then needs a later successful run that reaches it. After removal, a 404 is the retention model rather than a fault.

Write the result down the moment you have it. No endpoint can recover a swept job. Until they expire, the database's own recovery history (7 days) and weekly backups (kept 98 days) can still hold it; they are not reachable through the API, and Section 3 of the legal document describes them. If you receive callbacks onto a work queue, fetch the result on receipt rather than when the queue is next drained.

DELETE /v1/jobs/:jobId destroys it immediately, for a caller who would rather not wait for the sweep.

Timestamps are not ISO 8601 here

createdAt and updatedAt: this endpoint passes the stored timestamps through as raw database values — { "_seconds": 1786295642, "_nanoseconds": 0 } — rather than as ISO 8601 strings. Convert them yourself: new Date(_seconds * 1000 + _nanoseconds / 1e6).

It is inconsistent with the webhook payload, whose updatedAt is ISO 8601, and the inconsistency is a known defect in this endpoint rather than a design. It will be corrected. Until it is, do not build a string parser against this field, and do not assume the two sources agree in format just because they agree in meaning.

Request

Errors

A job your credential did not start answers 403: another organisation's job, one another API client of yours started, or one a person started in the web application or the API tester. A job that never existed or has been swept answers 404. Do not read a 404 as "still queued" — a queued job answers 200 with status: "QUEUED".