Background jobs
Long-running work such as imports, exports, health checks and crawls: list the jobs of one type, read one and cancel it.
Path parameters
The endpoints whose path names one of these take it as described here. An endpoint's own table lists a path parameter only when it describes it differently.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
jobId | path | integer (int64) | required | The job's id, as returned by the call that started it. |
Headers
The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Ken-Version | header | string, one of: 2026-11-02, 1.1 | optional | The API version, a date in YYYY-MM-DD form. 1.1 is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and 404 where the path exists only in this version. A date that is not a version answers 400 unsupported_version; any other value that is not a version is treated as legacy. |
X-Ken-Workspace-Id | header | integer (int64) | optional | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers 400 workspace_required. A workspace you are not a member of answers 404 not_found. |
List jobs
/v1/jobsjobs.list- Permission
- Any workspace member except a Network member
- Rate limit
- 12,000 requests a minute per API key
Lists the workspace's jobs of one type.
type is required: contact_import, contact_export, domain_health, lead_scoring, enrichment, crawl, extraction, batch_scrape, knowledge_export, inbox_import or migration. status keeps the jobs in any of the comma-separated statuses you pass. A knowledge_export list holds only your own exports. migration jobs list newest first. Every other type lists oldest first. limit is from 1 to 200, default 50. Pass pagination.nextCursor as cursor for the next page.
Each type needs a permission on top of workspace membership. crawl, extraction and batch_scrape need Search view. domain_health needs Delivery view. contact_import, lead_scoring and enrichment need Campaigns view. contact_export needs Campaigns view and the export permission. knowledge_export needs Knowledge view. migration needs the integrations permission. inbox_import needs nothing more. knowledge_export jobs also need the knowledge feature turned on for your workspace, and migration jobs the migrations feature. Until it is on, calls for that type answer 404.
Errors:
400 validation_failed:type,status,limitorcursoris not valid.403 permission_denied: you lack the permission the type needs.404 not_found: the feature the type needs is off for your workspace.
Open to any workspace member.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
type | query | string | optional | The job type: contact_import, contact_export, domain_health, lead_scoring, enrichment, crawl, extraction, batch_scrape, knowledge_export, inbox_import or migration. Required, because job ids repeat across types. |
status | query | string | optional | Only jobs in these statuses, as a comma-separated list of queued, running, succeeded, failed and canceled. Omitted returns every status. |
limit | query | integer (int32) | optional | Number of jobs per page, from 1 to 200. Default 50. |
cursor | query | string | optional | The nextCursor from the previous page. Omit it for the first page. |
curl -X GET "https://api.ken.so/v1/jobs?limit=50" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a list of Job. Each item has these fields. The response also carries pagination.
Show the 14 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get a job
/v1/jobs/{jobId}jobs.get- Permission
- Any workspace member except a Network member
- Rate limit
- 240 requests a minute per API key
Returns one job. Poll it until status is succeeded, failed or canceled.
Pass type when you know it: two types can share an id. Without it, Kenso looks for the id among the types you can read here, and answers as if you had passed the one type that has it. When more than one does, the call answers 400 validation_failed naming them, and you pass type. Each type needs the same permission as on GET /v1/jobs, and a type you cannot read is never looked in. When you poll, pass the type of the first answer: a read without it looks in every type each time. An inbox_import job carries inboxImport with counts and per-row results. One that makes no progress for 10 minutes reads failed with error.code interrupted. A crawl or batch_scrape read returns one page of results in result, about 10 MB at most. When result.next is not null, pass it back as cursor to read the next page. Other types ignore cursor. These two types count against the Heavy rate limit. An extraction reads running while it runs and failed once it fails, with the scraping provider's status in result. A read of a crawl, extraction or batch_scrape job sets the X-Ken-Web-Source and X-Ken-Credits-Charged headers. When the job runs on Kenso's key, Kenso charges its credits as status reads report progress.
Errors:
400 validation_failed:typeis unknown, or it is missing and more than one type you can read has this id.403 permission_denied: you lack the permission the type needs.404 not_found: the workspace has no job of this type with this id (or, withouttype, of any type you can read), the job is another member'sknowledge_export, or the feature the type needs is off.503 service_unavailable: the scraping provider answered without a status.
Open to any workspace member.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
type | query | string | optional | The job's type, as listed on GET /v1/jobs. Optional when the id is unique among the types you can read. |
cursor | query | string | optional | For a crawl or batch_scrape, the result.next of the previous read. Omit it for the first page. |
curl -X GET "https://api.ken.so/v1/jobs/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a Job.
Show the 14 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Cancel a job
/v1/jobs/{jobId}/canceljobs.cancel- Permission
- Search edit
- Rate limit
- 4,800 requests a minute per API key
Cancels a running crawl, batch_scrape or migration job and returns it. No other type can be canceled.
A canceled migration job stays running until the migration stops. On top of Search edit, the job's type needs the same permission as on GET /v1/jobs.
Errors:
400 validation_failed:typeis missing or unknown.403 permission_denied: you lack the permission the type needs.404 not_found: the workspace has no job of this type with this id, the job is another member'sknowledge_export, or the feature the type needs is off.409 invalid_state: the type cannot be canceled, or the job already finished.
Requires Search edit.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
type | query | string | optional | Required. The job's type: crawl, batch_scrape or migration. |
curl -X POST "https://api.ken.so/v1/jobs/812/cancel" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a Job.
Show the 14 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
More in Reporting:AnalyticsKenso statusAll resources