List import runs
const url = 'https://api.sloose.com/orgs/org_9f3c/runs?limit=50&connector=con_8f2a&import=imp_4d1a&kind=real%2Cretry';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/orgs/org_9f3c/runs?limit=50&connector=con_8f2a&import=imp_4d1a&kind=real%2Cretry' \ --header 'Authorization: Bearer <token>'Every run the organisation has authorised, newest first, whoever started it — a page at a time. connector narrows it to the runs through one connection, by the same rule as every route that takes one: an id this person may not use is 404 CONNECTION_NOT_FOUND. limit is the page size and cursor the nextCursor of the page before; from / to (an ISO date or timestamp; from inclusive, to exclusive) bound each run’s createdAt, the moment it was authorised — not startedAt, which an unfinished run may lack. The order is (createdAt, id), so a cursor is stable across inserts. A cursor is an opaque page boundary and nothing more: it names a place in this organisation’s own history, the same as from would, so one is refused only when it is malformed. History is retired nightly once it is older than the plan’s retention window, so an empty list on an old organisation is expected rather than an error.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The organisation id the session was issued for. A token for one organisation can never read another.
Example
org_9f3cThe organisation id the session was issued for. A token for one organisation can never read another.
Query Parameters
Section titled “Query Parameters”How many to return, at most 200; 50 when absent. Anything but a whole number above zero — 0, negative, a fraction, not a number — is the default, never an error.
Example
50How many to return, at most 200; 50 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.
Only the runs through this connection, by id: one of the organisation’s, or your own. Absent or empty: every run the organisation has, whichever connection it wrote to. Any other — another organisation’s, or another person’s — is 404 CONNECTION_NOT_FOUND.
Example
con_8f2aOnly the runs through this connection, by id: one of the organisation’s, or your own. Absent or empty: every run the organisation has, whichever connection it wrote to. Any other — another organisation’s, or another person’s — is 404 CONNECTION_NOT_FOUND.
Only the runs of this import, by id. An id the organisation has no import by answers an empty page, as every filter does.
Example
imp_4d1aOnly the runs of this import, by id. An id the organisation has no import by answers an empty page, as every filter does.
Only runs of these kinds, comma-separated (real, dry, retry) — real,retry for the runs that wrote, since a dry run writes nothing — it records what each write would have done (planned). Absent: every kind. An unknown kind is 400 INVALID_KIND.
Example
real,retryOnly runs of these kinds, comma-separated (real, dry, retry) — real,retry for the runs that wrote, since a dry run writes nothing — it records what each write would have done (planned). Absent: every kind. An unknown kind is 400 INVALID_KIND.
Only runs authorised (createdAt) at or after this ISO date or timestamp.
Only runs authorised (createdAt) at or after this ISO date or timestamp.
Only runs authorised (createdAt) before this ISO date or timestamp.
Only runs authorised (createdAt) before this ISO date or timestamp.
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 run charged as a FREE LINK, which counts no second run: a retry of a run’s failed rows, or a resume of a run its page left or a spent day stopped (#1659, #1969). A retry or a resume charged as a new run is real, like any run of its own. A free link is spent at its first ADMITTED row: one that ends with none admitted costs its run nothing and is handed back (the run can be retried free again), and a retry or a resume that names it stands below the run it named. What a run IS, a retry or a resume, is what it stands on and what it carried (GET …/runs/{run}/inherited), never this. A free link is free while the rows it writes are its chain’s, by their rowKey: one that wrote a row new to its chain past the rows its chain was counted for was counted as a run at that row, and still reads retry here. This is judged by key only while the chain’s keys are kept: a day after the chain last ran, or for a chain begun before keys were kept, a link’s rows are judged by the count it declared instead, as they were before, and no run is counted at a later row.
How many free links 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 free link is a retry or a resume (#1659, #1969); a resume of a run a spent day stopped takes none of the three. A retry of this run 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 link spent already (one that admitted a row). A free link keeps the meter’s own answer; on any other run it is worked out from the history, and is 0 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 link of (kind retry): the run it retried, or the run it picked up where a resume was free (#1659, #1969). Null for any other run — a retry or a resume 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.
What stopped the run, where the server saw it: allowance when a call of the run was refused because the CRM’s API allowance for the day was spent, and its page then closed it cancelled, or went before it closed and the server ended it abandoned. Its rows were not failed by that: the ones it had begun are kept with the run as left (not_reached in its records) and a resume takes them again, free of a run each time (dayLink on authorise). Null for every other run, and always for one whose status is neither cancelled nor abandoned — over_limit says what ended that run, and a run that finished was not stopped. Written by the server as it relays the refusal, never taken from the page.
Whether the run’s own page said it ended in order: it finished every call of every row it began and stopped at the top of a window (a person’s Stop, or the run’s own stop at the first failure), or reached the end of the file. The engine’s word, carried by the closing report as inOrder and kept only where the ledger ended the run as that close said, or stopped it at its row limit before the close arrived (over_limit: the limit refuses a row before its first write, so the page that ran it still knows whether every row it began was finished), the server saw nothing stop it (stoppedBy is null) and holds no unanswered attempt of it; the page leaves it out when an outcome report of the run was given up on or refused. Cleared by an unanswered attempt stored for the run after its close; never worked out from the status. True too for a complete the server wrote because the engine said it finished (#2237) and its page went before its close. False for a run a spent allowance stopped, one a sign-out, a reset or a replaced session ended mid-window, one the server ended without that word (abandoned, or over_limit whose page went before it closed), and a run recorded before this was kept. A reopened run whose last window may be unfinished is gone over from it, and one that is closedInOrder is not.
Whether a retry may follow this run (retryOf on authorise), by the run’s own record: 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. It says nothing of what the authorisation asks for itself, which may still refuse a retry of it. Among those refusals, each a 409: RUN_SUPERSEDED (the import has been run past it), RUN_SETTLING (its last writes are not yet written down), RUN_RECORDS_LOST (they could not be) and CONNECTION_MISMATCH (a run of its chain wrote to another connection than the import’s). Whether a retry is FREE — no second run counted — is narrower again, and the ledger’s: only of a run that ended complete, error or cancelled with failed rows and had no free retry spent before (a link that ended with no row admitted is given back, and a retry naming it stands below the run it named), and no more than three free retries in a row below a run the period counted. Any other retry the authorisation allows is charged as a new run: of a run with no failed rows, one whose free retry was spent already, one that is already the third free retry in a row, a run that was never a link and sent no row (it costs nothing and is not counted), 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 organisation 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 organisation 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", "stoppedBy": "allowance" } ]}cursor is malformed (code: INVALID_CURSOR), from / to is not an ISO date or timestamp (code: INVALID_DATE), or kind names a kind there is not (code: INVALID_KIND).
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 bearer, or one that no longer resolves: a session that is unknown or expired (code: AUTH_REQUIRED), or an API token that was revoked or expired (TOKEN_REVOKED, TOKEN_EXPIRED), whose organisation is gone (ORG_NOT_FOUND) or whose member or user row is (MEMBERSHIP_GONE).
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"}The bearer’s role is too low (code: ROLE_REQUIRED), or it was issued for a different organisation; the organisation has been closed (code: ORG_CLOSED, either kind of bearer); the person is banned (code: BANNED, a session); or it is a session that is signed in but in no organisation (code: NO_ORG): one that never joined one, or whose person was taken out of the one it was in, or left it. Signing in again changes nothing for NO_ORG; choosing or making an organisation does.
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"}?connector= names a connection this person may not use: another organisation’s, or another person’s (code: CONNECTION_NOT_FOUND).
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"}The restore switch is on (code: MAINTENANCE): every route but /health and /robots.txt is refused before anything is read, except the operator’s own POST /staff/people/{id}/delete with the ADMIN_TOKEN. Sloose is down for maintenance. Please try again in a few minutes.
object
Example
{ "code": "MAINTENANCE"}Headers
Section titled “Headers”Seconds until asking again is worth it (300 while the switch is on).