One org’s runs
const url = 'https://api.sloose.com/staff/orgs/org_9f3c/runs?limit=10';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://api.sloose.com/staff/orgs/org_9f3c/runs?limit=10' \ --header 'Authorization: Bearer <token>'Backoffice route: a staff session, or ADMIN_TOKEN. Every run the org has authorised, newest first, a page at a time: limit and cursor — the runsNextCursor of GET /staff/orgs/{orgId}, or the nextCursor of the page before — answering nextCursor, null on the last page. In (createdAt, id) order, so a run authorised while somebody reads is never shown twice. Every page is written down as a look (org.view, with detail.of runs), as the detail is: a run carries the org’s own words — its modules and its errors — and a cursor is a place anybody may name, so this route is no continuation the detail’s own record could vouch for.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The org
Example
org_9f3cThe org
Query Parameters
Section titled “Query Parameters”How many to return, at most 200; 10 when absent. Anything but a whole number above zero — 0, negative, a fraction, not a number — is the default, never an error.
Example
10How many to return, at most 200; 10 when absent. Anything but a whole number above zero — 0, negative, a fraction, not a number — is the default, never an error.
The nextCursor of the page before this one; absent for the first page. Opaque: it names a place in the list’s (createdAt, id) order, and a malformed one is 400 INVALID_CURSOR.
The nextCursor of the page before this one; absent for the first page. Opaque: it names a place in the list’s (createdAt, id) order, and a malformed one is 400 INVALID_CURSOR.
Responses
Section titled “Responses”A page of runs, newest first.
object
One import run. Retired nightly past the plan’s history window.
object
The connection this run wrote to: its import’s, or the one the authorising request named — a run always names one, for a token as much as for a person (design §14.8). Null only on a run recorded before connections were named.
The import this run ran; null for a run recorded before imports were stored.
dry writes nothing and is free. retry is a retry charged as a FREE one: it runs the rows a run before it did not finish, and counts no second run. A retry charged as a new run is real, like any run of its own.
How many free retries in a row are left below this run: the chain’s three (a run of its own, which heads a chain once the period counts it, keeps all three) less the free link this run is. A retry of it is free only while this is above 0, and only if the run ended as the client said, with failed rows, and has had no free retry already. 0 too when the history cannot walk the run’s chain to its top — the purge took a run above it — which the meter reads as not free; the meter keeps every link, and may still charge such a retry as free.
The run this one was charged as a FREE retry of (kind retry). Null for any other run — a retry charged as a new run included, whose inheritance says what it stands on (GET …/runs/{run}/inherited) — and once the history’s purge has taken the run it named.
The template version the import had copied when this ran.
The import’s version when the run took it: what the run ran is what that version said.
authorised is the server opening the run; running, complete, cancelled and error are the client saying how it went. over_limit is the SERVER stopping one that reported past the rows allowed in a single import — the error field then carries which limit and what it was, because the status on its own tells nobody. refused and abandoned belong to an import’s run: the ledger refusing one whose claim was already taken (the claim is released at once), and the server closing one whose client stopped renewing its lease.
Whether a retry may follow this run (retryOf on authorise): it has ended, however it ended, it was no dry run, and the history’s purge has not begun to take it (purgeStartedAt) — whatever it wrote. A retry of it inherits what its chain made. Whether that retry is FREE — no second run counted — is narrower, and the ledger’s: only of a run that ended complete, error or cancelled with failed rows and had no free retry before, and no more than three free retries in a row below a run the period counted. Any other retry is still allowed, and charged as a new run: of a run with no failed rows, one retried free already, one that is already the third free retry in a row, a run of its own that sent no row, or one stopped at its row limit (over_limit) or abandoned.
When the nightly purge began to remove this run, past its plan’s history_days; null until then. Its records go before its row — and its row stays when they would not all delete — so from then on what it made cannot be read in full, and a retry of it is refused (409 RUN_RETIRED).
Who ran it, joined from the user row rather than left as an id — a person who has since left the org is in no member list the caller could look them up in. An API token acts as its creator, so this is filled in for a token’s run too: read tokenId/tokenName before attributing a run to a person.
The org API token that authorised it, or null for a person. Set from the session, so a run made with a token is distinguishable from one the same person made in the browser.
What that token is called, joined from the token row. Survives revocation, because revoking keeps the row.
What the destination is called here, joined from the connector row. Null exactly when connectorId is — see the three causes there, only two of which are historical.
Pass as cursor for the next page; null when this was the last.
Example
{ "runs": [ { "kind": "real", "mode": "widget", "status": "authorised" } ]}cursor is malformed (code: INVALID_CURSOR).
The error envelope every non-2xx answer uses.
object
Human-readable explanation.
Machine-readable reason. Absent on a few legacy 400s.
Examplegenerated
{ "error": "example", "code": "example"}A bearer that is neither the token nor a live session (code: AUTH_REQUIRED).
The error envelope every non-2xx answer uses.
object
Human-readable explanation.
Machine-readable reason. Absent on a few legacy 400s.
Examplegenerated
{ "error": "example", "code": "example"}A customer’s session, an API token, or no bearer at all — not staff, and not the ADMIN_TOKEN (code: ADMIN_REQUIRED).
The error envelope every non-2xx answer uses.
object
Human-readable explanation.
Machine-readable reason. Absent on a few legacy 400s.
Examplegenerated
{ "error": "example", "code": "example"}No such org, or it is not visible to this session.
The error envelope every non-2xx answer uses.
object
Human-readable explanation.
Machine-readable reason. Absent on a few legacy 400s.
Examplegenerated
{ "error": "example", "code": "example"}