Owlbound
Browse the docs

Reference · 7 operations

Tables: column runs

Last updated from API version 2026-10-06 at (live spec, refreshed hourly). openapi.json

Runs

tables.runs.estimate

Estimate a column run (free, nothing held).

post/api/v1/tables/{id}/columns/{columnId}/runs/estimate
Scope
read
Credits
Free
Idempotency-Key
none

What a run of this column over scope would cost, priced from the server catalog: cells, creditsMin (no enrichment match; AI cells always cost), creditsMax (every cell charged), byCapability, walletAvailable (null when unlimited) and excluded (cells that already ran, unless scope.force, and cells another run is working on). During a migration (shadow) every run endpoint is 409 TABLE_MIGRATING.

Parameters

  • idpathstringrequired

    The table id.

  • columnIdpathstringrequired

    The column id (a formula, ai, enrichment or action column).

Request body · application/json

TableRunEstimateRequest

  • scopeTableRunScope

    Which cells a run takes. mode: all (default), empty (cell empty), errored / skipped / stale (by cell state), selected (rowIds, at most 1,000), view (viewId). filter (the rows filter language) narrows all, empty and view. Cells that already ran are left out unless force (a new charge).

    0
  • maxCreditsnumber
    0

Responses

200
OK.
Show schema

TableRunEstimateResponse

Errors

400 The request is invalid (VALIDATION_ERROR, CURSOR_MISMATCH, UNSUPPORTED_FILTER) · 401 Missing, invalid, expired or revoked key · 403 Missing scope, suspended workspace or unavailable identity · 404 Unknown resource or route. A resource in another workspace is also 404 · 409 IDEMPOTENCY_IN_PROGRESS (the first request with this key is still running; `Retry-After` is the lease left, at most 60 s) or IDEMPOTENCY_RESULT_UNAVAILABLE (the original result was too large to store; `details.originalRequestId`). · 422 IDEMPOTENCY_KEY_REUSED (the key was used with another body or operation), or an action that cannot run · 429 Rate limit reached · 500 Unexpected error · 503 The backend is unreachable; retry after `Retry-After`. Every error is {error: {type, code, message, requestId, docUrl}}; see error codes.

curl -X POST "https://app.owlbound.ai/api/v1/tables/$ID/columns/$COLUMN_ID/runs/estimate" \
  -H "Authorization: Bearer $OWLBOUND_API_KEY" \
  -H "Owlbound-Version: 2026-10-06" \
  -H "Content-Type: application/json" \
  -d '{
  "scope": {
    "mode": "all",
    "rowIds": [
      "<rowIds>"
    ],
    "viewId": "<viewId>"
  },
  "maxCredits": 100
}'

tables.runs.create

Run a column (formula, ai, enrichment or action).

post/api/v1/tables/{id}/columns/{columnId}/runs
Scope
enrich
Credits
Free
Idempotency-Key
required

Queues one cell per row of scope and returns 202 with the run. The engine then forms batches of up to 25 cells whose maximum cost fits maxCredits (required) and the column's daily cap, holds credits per batch and capability, and settles what committed cells charged: enrichment only for a value, AI for a value or no_result, errors never, formula never. An action column holds the operation's catalog price only for rows whose priced step can run (others hold nothing) and charges it once per row whose result the operation charges (e.g. a newly found work email). A run that reaches maxCredits ends capped (cells skipped with RUN_CAPPED). 402 INSUFFICIENT_CREDITS when the wallet cannot cover creditsMin; 429 CAP_EXCEEDED when the column's daily cap is reached. Cells that already ran are re-run only with scope.force (a new charge).

Parameters

  • idpathstringrequired

    The table id.

  • columnIdpathstringrequired

    The column id (a formula, ai, enrichment or action column).

  • Idempotency-Keyheaderstring

    1 to 255 printable ASCII characters, scoped to the API key (a rotated key shares its predecessor's keys) and kept 24 h. Accepted on every POST, PATCH and DELETE (ignored on GET); required from v1 keys where the operation says x-owlbound-idempotent: required (missing: 400 VALIDATION_ERROR, param: Idempotency-Key). Same key and body after completion: the stored response is replayed with Idempotent-Replayed: true. Results over 64 KB are not stored; their replay is 409 IDEMPOTENCY_RESULT_UNAVAILABLE with details.originalRequestId (check state with a GET). Same key while the first request runs: 409 IDEMPOTENCY_IN_PROGRESS with Retry-After. Same key, other body or operation: 422 IDEMPOTENCY_KEY_REUSED. A request that ended 5xx may be retried with the same key. 4xx results are stored and replayed too: a 402 INSUFFICIENT_CREDITS replays even after a top-up, so use a new Idempotency-Key after adding credits.

    min length 1max length 255

Request body (required) · application/json

TableRunCreateRequest

  • scopeTableRunScope

    Which cells a run takes. mode: all (default), empty (cell empty), errored / skipped / stale (by cell state), selected (rowIds, at most 1,000), view (viewId). filter (the rows filter language) narrows all, empty and view. Cells that already ran are left out unless force (a new charge).

    0
  • maxCreditsnumberrequired

    The most this run may charge; batches are formed under it.

    min 0

Responses

202
Accepted: the run is queued; the engine reserves and charges per batch.
Show schema

TableRunResponse

Errors

400 The request is invalid (VALIDATION_ERROR, CURSOR_MISMATCH, UNSUPPORTED_FILTER) · 401 Missing, invalid, expired or revoked key · 402 Not enough credits (INSUFFICIENT_CREDITS). With an Idempotency-Key this result is stored and replayed: after adding credits, retry with a new Idempotency-Key. · 403 Missing scope, suspended workspace or unavailable identity · 404 Unknown resource or route. A resource in another workspace is also 404 · 409 IDEMPOTENCY_IN_PROGRESS (the first request with this key is still running; `Retry-After` is the lease left, at most 60 s) or IDEMPOTENCY_RESULT_UNAVAILABLE (the original result was too large to store; `details.originalRequestId`). · 422 IDEMPOTENCY_KEY_REUSED (the key was used with another body or operation), or an action that cannot run · 429 Rate limit reached · 500 Unexpected error · 503 The backend is unreachable; retry after `Retry-After`. Every error is {error: {type, code, message, requestId, docUrl}}; see error codes.

curl -X POST "https://app.owlbound.ai/api/v1/tables/$ID/columns/$COLUMN_ID/runs" \
  -H "Authorization: Bearer $OWLBOUND_API_KEY" \
  -H "Owlbound-Version: 2026-10-06" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "maxCredits": 100
}'

tables.runs.list

The table's column runs, newest first.

get/api/v1/tables/{id}/runs
Scope
read
Credits
Free
Idempotency-Key
Not used

Each run with its status, scope, estimate, cap, cell counts and credits (reserved: holds still open; charged: settled).

Parameters

  • idpathstringrequired

    The table id.

  • limitqueryinteger

    Page size.

    default 50min 1max 200
  • cursorquerystring

    Opaque cursor from meta.page.nextCursor. Reusing it with other filters is 400 CURSOR_MISMATCH.

Responses

200
OK.
Show schema

TableRunListResponse

Errors

400 The request is invalid (VALIDATION_ERROR, CURSOR_MISMATCH, UNSUPPORTED_FILTER) · 401 Missing, invalid, expired or revoked key · 403 Missing scope, suspended workspace or unavailable identity · 404 Unknown resource or route. A resource in another workspace is also 404 · 409 IDEMPOTENCY_IN_PROGRESS (the first request with this key is still running; `Retry-After` is the lease left, at most 60 s) or IDEMPOTENCY_RESULT_UNAVAILABLE (the original result was too large to store; `details.originalRequestId`). · 429 Rate limit reached · 500 Unexpected error · 503 The backend is unreachable; retry after `Retry-After`. Every error is {error: {type, code, message, requestId, docUrl}}; see error codes.

curl "https://app.owlbound.ai/api/v1/tables/$ID/runs" \
  -H "Authorization: Bearer $OWLBOUND_API_KEY" \
  -H "Owlbound-Version: 2026-10-06"

tables.runs.get

One column run.

get/api/v1/tables/{id}/runs/{runId}
Scope
read
Credits
Free
Idempotency-Key
Not used

Status queued, running, done, capped, cancelled or failed; finishedAt is set once nothing is queued or held.

Parameters

  • idpathstringrequired

    The table id.

  • runIdpathstringrequired

    The run id.

Responses

200
OK.
Show schema

TableRunResponse

Errors

400 The request is invalid (VALIDATION_ERROR, CURSOR_MISMATCH, UNSUPPORTED_FILTER) · 401 Missing, invalid, expired or revoked key · 403 Missing scope, suspended workspace or unavailable identity · 404 Unknown resource or route. A resource in another workspace is also 404 · 409 IDEMPOTENCY_IN_PROGRESS (the first request with this key is still running; `Retry-After` is the lease left, at most 60 s) or IDEMPOTENCY_RESULT_UNAVAILABLE (the original result was too large to store; `details.originalRequestId`). · 429 Rate limit reached · 500 Unexpected error · 503 The backend is unreachable; retry after `Retry-After`. Every error is {error: {type, code, message, requestId, docUrl}}; see error codes.

curl "https://app.owlbound.ai/api/v1/tables/$ID/runs/$RUN_ID" \
  -H "Authorization: Bearer $OWLBOUND_API_KEY" \
  -H "Owlbound-Version: 2026-10-06"

tables.runs.cells

The run's cells: per-cell status, attempts and charge.

get/api/v1/tables/{id}/runs/{runId}/cells
Scope
read
Credits
Free
Idempotency-Key
Not used

One entry per cell of the run (the cell's run history for this run): status, batch, attempts and attempt log, capability and credits charged (chargedAt set once, with the committed outcome).

Parameters

  • idpathstringrequired

    The table id.

  • runIdpathstringrequired

    The run id.

  • limitqueryinteger

    Page size.

    default 50min 1max 200
  • cursorquerystring

    Opaque cursor from meta.page.nextCursor. Reusing it with other filters is 400 CURSOR_MISMATCH.

Responses

200
OK.
Show schema

TableCellRunListResponse

Errors

400 The request is invalid (VALIDATION_ERROR, CURSOR_MISMATCH, UNSUPPORTED_FILTER) · 401 Missing, invalid, expired or revoked key · 403 Missing scope, suspended workspace or unavailable identity · 404 Unknown resource or route. A resource in another workspace is also 404 · 409 IDEMPOTENCY_IN_PROGRESS (the first request with this key is still running; `Retry-After` is the lease left, at most 60 s) or IDEMPOTENCY_RESULT_UNAVAILABLE (the original result was too large to store; `details.originalRequestId`). · 429 Rate limit reached · 500 Unexpected error · 503 The backend is unreachable; retry after `Retry-After`. Every error is {error: {type, code, message, requestId, docUrl}}; see error codes.

curl "https://app.owlbound.ai/api/v1/tables/$ID/runs/$RUN_ID/cells" \
  -H "Authorization: Bearer $OWLBOUND_API_KEY" \
  -H "Owlbound-Version: 2026-10-06"

tables.runs.cancel

Cancel a run.

post/api/v1/tables/{id}/runs/{runId}/cancel
Scope
enrich
Credits
Free
Idempotency-Key
optional

Queued cells are skipped (CANCELLED); batches that committed nothing release their hold; batches with committed cells settle what they charged. Cancelling a finished run returns it unchanged.

Parameters

  • idpathstringrequired

    The table id.

  • runIdpathstringrequired

    The run id.

  • Idempotency-Keyheaderstring

    1 to 255 printable ASCII characters, scoped to the API key (a rotated key shares its predecessor's keys) and kept 24 h. Accepted on every POST, PATCH and DELETE (ignored on GET); required from v1 keys where the operation says x-owlbound-idempotent: required (missing: 400 VALIDATION_ERROR, param: Idempotency-Key). Same key and body after completion: the stored response is replayed with Idempotent-Replayed: true. Results over 64 KB are not stored; their replay is 409 IDEMPOTENCY_RESULT_UNAVAILABLE with details.originalRequestId (check state with a GET). Same key while the first request runs: 409 IDEMPOTENCY_IN_PROGRESS with Retry-After. Same key, other body or operation: 422 IDEMPOTENCY_KEY_REUSED. A request that ended 5xx may be retried with the same key. 4xx results are stored and replayed too: a 402 INSUFFICIENT_CREDITS replays even after a top-up, so use a new Idempotency-Key after adding credits.

    min length 1max length 255

Responses

200
OK.
Show schema

TableRunResponse

Errors

400 The request is invalid (VALIDATION_ERROR, CURSOR_MISMATCH, UNSUPPORTED_FILTER) · 401 Missing, invalid, expired or revoked key · 403 Missing scope, suspended workspace or unavailable identity · 404 Unknown resource or route. A resource in another workspace is also 404 · 409 IDEMPOTENCY_IN_PROGRESS (the first request with this key is still running; `Retry-After` is the lease left, at most 60 s) or IDEMPOTENCY_RESULT_UNAVAILABLE (the original result was too large to store; `details.originalRequestId`). · 422 IDEMPOTENCY_KEY_REUSED (the key was used with another body or operation), or an action that cannot run · 429 Rate limit reached · 500 Unexpected error · 503 The backend is unreachable; retry after `Retry-After`. Every error is {error: {type, code, message, requestId, docUrl}}; see error codes.

curl -X POST "https://app.owlbound.ai/api/v1/tables/$ID/runs/$RUN_ID/cancel" \
  -H "Authorization: Bearer $OWLBOUND_API_KEY" \
  -H "Owlbound-Version: 2026-10-06" \
  -H "Idempotency-Key: $(uuidgen)"

Cells

tables.cells.retry

Run one cell again.

post/api/v1/tables/{id}/rows/{rowId}/cells/{columnId}/retry
Scope
enrich
Credits
Free
Idempotency-Key
required

A new run of one cell (trigger retry), 202. A cell that already has a result needs force: true (a new charge); a cell queued or running in another run is refused. maxCredits defaults to the cell's maximum cost.

Parameters

  • idpathstringrequired

    The table id.

  • rowIdpathstringrequired

    The row id.

  • columnIdpathstringrequired

    The column id (a formula, ai, enrichment or action column).

  • Idempotency-Keyheaderstring

    1 to 255 printable ASCII characters, scoped to the API key (a rotated key shares its predecessor's keys) and kept 24 h. Accepted on every POST, PATCH and DELETE (ignored on GET); required from v1 keys where the operation says x-owlbound-idempotent: required (missing: 400 VALIDATION_ERROR, param: Idempotency-Key). Same key and body after completion: the stored response is replayed with Idempotent-Replayed: true. Results over 64 KB are not stored; their replay is 409 IDEMPOTENCY_RESULT_UNAVAILABLE with details.originalRequestId (check state with a GET). Same key while the first request runs: 409 IDEMPOTENCY_IN_PROGRESS with Retry-After. Same key, other body or operation: 422 IDEMPOTENCY_KEY_REUSED. A request that ended 5xx may be retried with the same key. 4xx results are stored and replayed too: a 402 INSUFFICIENT_CREDITS replays even after a top-up, so use a new Idempotency-Key after adding credits.

    min length 1max length 255

Request body · application/json

TableCellRetryRequest

  • forceboolean
    0
  • maxCreditsnumber
    min 0

Responses

202
Accepted: the run is queued; the engine reserves and charges per batch.
Show schema

TableRunResponse

Errors

400 The request is invalid (VALIDATION_ERROR, CURSOR_MISMATCH, UNSUPPORTED_FILTER) · 401 Missing, invalid, expired or revoked key · 402 Not enough credits (INSUFFICIENT_CREDITS). With an Idempotency-Key this result is stored and replayed: after adding credits, retry with a new Idempotency-Key. · 403 Missing scope, suspended workspace or unavailable identity · 404 Unknown resource or route. A resource in another workspace is also 404 · 409 IDEMPOTENCY_IN_PROGRESS (the first request with this key is still running; `Retry-After` is the lease left, at most 60 s) or IDEMPOTENCY_RESULT_UNAVAILABLE (the original result was too large to store; `details.originalRequestId`). · 422 IDEMPOTENCY_KEY_REUSED (the key was used with another body or operation), or an action that cannot run · 429 Rate limit reached · 500 Unexpected error · 503 The backend is unreachable; retry after `Retry-After`. Every error is {error: {type, code, message, requestId, docUrl}}; see error codes.

curl -X POST "https://app.owlbound.ai/api/v1/tables/$ID/rows/$ROW_ID/cells/$COLUMN_ID/retry" \
  -H "Authorization: Bearer $OWLBOUND_API_KEY" \
  -H "Owlbound-Version: 2026-10-06" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "force": false,
  "maxCredits": 100
}'

Models on this page

Shared objects the operations above link to. Clients must ignore fields they do not know.

TableRunScopeobject

Which cells a run takes. mode: all (default), empty (cell empty), errored / skipped / stale (by cell state), selected (rowIds, at most 1,000), view (viewId). filter (the rows filter language) narrows all, empty and view. Cells that already ran are left out unless force (a new charge).

  • modestring
    allemptyerroredskippedstaleselectedview
  • rowIdsarray of string
    0
  • viewIdstring
    0
  • filterany
    0
  • forceboolean
    0
TableRunEstimateobject
  • cellsintegerrequired
    0
  • creditsMinnumberrequired
    0
  • creditsMaxnumberrequired
    0
  • byCapabilityarray of TableRunCapabilityEstimaterequired
    0
  • walletAvailablenumber | nullrequired
    0
  • excludedobjectrequired
    0
    + Show child fields
    • doneintegerrequired
      0
    • activeintegerrequired
      0
TableRunCapabilityEstimateobject
  • capabilityIdstringrequired
    0
  • cellsintegerrequired
    0
  • unitCreditsnumberrequired
    0
  • creditsMinnumberrequired
    0
  • creditsMaxnumberrequired
    0
ResponseMetaobject

Metadata on every success response.

  • requestIdstringrequired
    0
  • creditsCreditsMetarequired
    0
  • pagePageMeta

    Cursor pagination. hasMore is the only end signal; pages may be short.

    0
  • dryRunboolean

    True only on a dry-run response (action operations).

    0
CreditsMetaobject
  • usednumberrequired

    Credits charged by this request. Reads are free.

    0
  • balancenumber
    0
  • estimatednumber

    Dry run only (action operations).

    0
  • availablenumber

    Dry run only (action operations).

    0
  • reservationIdstring | null

    Async operations only; the job settles this reservation.

    0
PageMetaobject

Cursor pagination. hasMore is the only end signal; pages may be short.

  • nextCursorstring | nullrequired
    0
  • hasMorebooleanrequired
    0
  • limitintegerrequired
    min 1max 200
TableRunobject
  • idstringrequired
    0
  • workspaceIdstringrequired
    0
  • tableIdstringrequired
    0
  • columnIdstringrequired
    0
  • triggerstringrequired
    apiuiretryauto_runsource_sync
  • scopeTableRunScoperequired

    Which cells a run takes. mode: all (default), empty (cell empty), errored / skipped / stale (by cell state), selected (rowIds, at most 1,000), view (viewId). filter (the rows filter language) narrows all, empty and view. Cells that already ran are left out unless force (a new charge).

    0
  • statusstringrequired
    queuedrunningdonecancelledfailedcapped
  • estimateanyrequired
    0
  • maxCreditsnumberrequired
    0
  • cellsobjectrequired
    0
    + Show child fields
    • totalintegerrequired
      0
    • doneintegerrequired
      0
    • failedintegerrequired
      0
    • skippedintegerrequired
      0
  • creditsobjectrequired
    0
    + Show child fields
    • reservednumberrequired
      0
    • chargednumberrequired
      0
  • createdAtnumberrequired
    0
  • finishedAtnumber | nullrequired
    0
PagedResponseMetaobject

Metadata on a paginated success response.

  • requestIdstringrequired
    0
  • creditsCreditsMetarequired
    0
  • pagePageMetarequired

    Cursor pagination. hasMore is the only end signal; pages may be short.

    0
TableCellRunobject
  • idstringrequired
    0
  • runIdstringrequired
    0
  • rowIdstringrequired
    0
  • columnIdstringrequired
    0
  • statusstringrequired
    queuedrunningdoneno_resulterrorstaleskipped
  • batchNointeger | nullrequired
    0
  • attemptsintegerrequired
    0
  • attemptLogarray of objectrequired
    0
  • capabilityIdstring | nullrequired
    0
  • creditsChargednumberrequired
    0
  • chargedAtnumber | nullrequired
    0
  • startedAtnumber | nullrequired
    0
  • finishedAtnumber | nullrequired
    0

← All operations