Skip to Content
Reporting

Background jobs

Long-running work such as imports, exports, health checks and crawls: list the jobs of one type, read one and cancel it.

Reporting3 endpointsKen-Version: 2026-11-02AuthenticationWorkspacesErrors
MarkdownOpenAPI

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.

NameInTypeRequiredDescription
jobIdpathinteger (int64)requiredThe 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.

NameInTypeRequiredDescription
Ken-Versionheaderstring, one of: 2026-11-02, 1.1optionalThe 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-Idheaderinteger (int64)optionalThe 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

GET/v1/jobsjobs.list
Permission
Any workspace member except a Network member
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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, limit or cursor is 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

NameInTypeRequiredDescription
typequerystringoptionalThe 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.
statusquerystringoptionalOnly jobs in these statuses, as a comma-separated list of queued, running, succeeded, failed and canceled. Omitted returns every status.
limitqueryinteger (int32)optionalNumber of jobs per page, from 1 to 200. Default 50.
cursorquerystringoptionalThe nextCursor from the previous page. Omit it for the first page.
Request
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

GET/v1/jobs/{jobId}jobs.get
Permission
Any workspace member except a Network member
Rate limit
240 requests a minute per API key

Try it on developer.ken.so

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: type is 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, without type, of any type you can read), the job is another member's knowledge_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

NameInTypeRequiredDescription
typequerystringoptionalThe job's type, as listed on GET /v1/jobs. Optional when the id is unique among the types you can read.
cursorquerystringoptionalFor a crawl or batch_scrape, the result.next of the previous read. Omit it for the first page.
Request
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

POST/v1/jobs/{jobId}/canceljobs.cancel
Permission
Search edit
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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: type is 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's knowledge_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

NameInTypeRequiredDescription
typequerystringoptionalRequired. The job's type: crawl, batch_scrape or migration.
Request
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.


On this page