Cancel a library import

A queued import becomes canceled at once.

POST/library/imports/{import_id}/cancel

Required scope: library:write
Authentication: Authorization: Bearer
Rate-limit policy: writeaccount

A running import becomes canceling and ends canceled when the work stops (a transcript that was already fetched or was finishing still reaches your library and is charged as usual). Canceling an import that is already canceling or canceled returns it unchanged; a succeeded or failed import answers 409 import_not_cancelable.

Parameters

Parameters
Name	In	Type	Required	Default	Constraints	Description
`import_id`	path	`string`	required	–	26–26 characters · pattern: ^imp_[0-9A-Za-z]{22}$	Public import ID (`imp_` prefix).
`Idempotency-Key`	header	`string`	no	–	8–255 characters · pattern: ^[A-Za-z0-9_\-:.]{8,255}$	Makes a retry safe: the same key with the same request returns the first answer (`Idempotent-Replayed: true`); a different request under the same key is rejected with 422 `idempotency_key_reused`. 8-255 characters from A-Z a-z 0-9 _ - : . Kept for 24 hours.

Response

200

The import after the cancel request.

Idempotent-Replayed true when the response is a replay of an earlier request with the same Idempotency-Key.
RateLimit The most restrictive policy that applied: "name";r=<requests left>;t=<seconds>, where t is the number of seconds until one more request is allowed (0 when the quota is full). Absent when no rate limiter ran for the request.
RateLimit-Policy The rate-limit policies that applied to the request, one "name";q=<burst>;w=<seconds> item per policy, for example "read";q=10;w=2, "account";q=20;w=2: q is the burst quota and w the seconds in which an empty quota refills. Sent on every authenticated response; absent when no rate limiter ran for the request, for example when it was rejected before the key was checked.
Request-Id ID of this request (req_ prefix), the same as request_id in an error body. It is also sent as X-Request-ID. Quote it when you contact support.
X-Client-Request-Id Your own X-Client-Request-Id request header, echoed back. It is sent only when the value you sent has 1-128 characters from A-Z a-z 0-9 . _ : -.
X-RateLimit-Limit Burst quota of the most restrictive policy (q in RateLimit-Policy). Absent when no rate limiter ran.
X-RateLimit-Remaining Requests left in the most restrictive policy (r in RateLimit). Absent when no rate limiter ran.
X-RateLimit-Reset Seconds until one more request is allowed in the most restrictive policy (t in RateLimit; 0 when the quota is full). It is a number of seconds, not a timestamp. Absent when no rate limiter ran.

Content type: application/json

idstringrequired
Public import ID (imp_ prefix).
26–26 characters · pattern: ^imp_[0-9A-Za-z]{22}$
objectstringrequired
Always library_import.
statusstringrequired
Import status.
Allowed values: queuedprocessingcancelingsucceededfailedcanceled
stagestring | nullrequired
Current stage; only while processing.
Allowed values: captionswaitingdownloadingtranscribingsummarizing
queue_positioninteger | nullrequired
Position among your queued imports (1 = next); null when the import is not queued.
1–2147483647 · format: int32
urlstringrequired
Canonical YouTube URL.
format: uri
youtube_video_idstringrequired
YouTube video ID.
languagestring | nullrequired
Language hint that was sent, or null.
Allowed values: lten
reusedbooleanrequired
True when the video was already in your library or in Diko's shared cache, so no credits were used.
transcript_idstring | nullrequired
ID (trn_ prefix) of the library transcript once the import has succeeded; otherwise null.
6–64 characters · pattern: ^trn_[A-Za-z0-9_-]+$
errorobject | nullrequired
Error details when the import failed; otherwise null.
2 fields
- codestringrequired
  Stable error code. Unknown internal codes are reported as internal_error.
  Allowed values: video_unavailablevideo_privateage_restrictedvideo_too_longvideo_duration_unknowncaptions_unavailabledownload_failedtranscription_failedtranscription_timeoutprovider_limitinsufficient_creditsinternal_error
- messagestringrequired
  Explanation in the language of Accept-Language.
created_atstringrequired
When the import was created.
≤ 24 characters · format: date-time
updated_atstringrequired
When the import last changed.
≤ 24 characters · format: date-time
completed_atstring | nullrequired
When the import reached a final status; otherwise null.
≤ 24 characters · format: date-time

Examples

Request

cURL

curl -X POST "https://api.diko.app/api/v1/library/imports/imp_7Qw3eR5tY8uI1oP4aS6dFg/cancel" \
  -H "Authorization: Bearer $DIKO_API_KEY"

Python

import os

import requests

response = requests.post(
    "https://api.diko.app/api/v1/library/imports/imp_7Qw3eR5tY8uI1oP4aS6dFg/cancel",
    headers={"Authorization": f"Bearer {os.environ['DIKO_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

TypeScript

const response = await fetch("https://api.diko.app/api/v1/library/imports/imp_7Qw3eR5tY8uI1oP4aS6dFg/cancel", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DIKO_API_KEY}`,
  },
})
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`)
console.log(await response.json())

Example response · 200 · application/json

JSON

{
  "id": "imp_6Mfj7Oxm4MfxGGmZRhiUQf",
  "object": "library_import",
  "status": "canceling",
  "stage": "downloading",
  "queue_position": null,
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "youtube_video_id": "dQw4w9WgXcQ",
  "language": "lt",
  "reused": false,
  "transcript_id": null,
  "error": null,
  "created_at": "2026-10-11T09:30:00.000Z",
  "updated_at": "2026-10-11T09:30:00.100Z",
  "completed_at": null
}

Errors

This endpoint can return these errors. Every code is described in the error catalog.

HTTP	Code	Meaning	Retry?
400	`idempotency_key_invalid`	The `Idempotency-Key` is invalid: it needs 8 to 255 characters from `A-Z a-z 0-9 _ - : .`.	no
401	`missing_api_key`	The request has no `Authorization` header.	no
401	`invalid_api_key`	The header is unusable (a scheme other than `Bearer`, an empty key or more than one `Authorization` header) or the key is unknown or malformed (wrong structure or checksum). The response is identical in all these cases.	no
401	`api_key_expired`	The key has expired.	no
401	`api_key_revoked`	The key was revoked: manually, after a rotation grace period ended, because of a leak or because the account was disabled.	no
401	`api_key_disabled`	The key is temporarily disabled.	no
402	`subscription_required`	The account has no active paid access.	no
403	`ip_not_allowed`	The key has an IP allowlist and the request IP is not on it, or it cannot be determined reliably.	no
403	`account_disabled`	The account is disabled.	no
403	`email_not_verified`	The account e-mail address is not verified.	no
403	`api_access_suspended`	A Diko administrator suspended API access for this account.	no
403	`plan_required`	The plan does not include the API. `error.details.required_plans` lists `verslas`.	no
403	`insufficient_scope`	The key lacks the scope this endpoint needs. `error.details` contains `required_scopes` and `granted_scopes`.	no
404	`not_found`	The resource does not exist, does not belong to your account or its ID is encoded incorrectly.	no
409	`import_not_cancelable`	The import has already finished (`succeeded` or `failed`) and can no longer be canceled.	no
409	`idempotency_in_progress`	The same request with the same `Idempotency-Key` is still being processed.	yes, after Retry-After
422	`idempotency_key_reused`	The same `Idempotency-Key` was used with a different method, path or body.	no
429	`rate_limit_exceeded`	A rate-limit policy was exceeded. `error.details.policy` names it.	yes, after Retry-After
500	`internal_error`	An internal server error.	conditionally
503	`writes_disabled`	Write operations are temporarily switched off on the platform side. Reading still works.	yes, after Retry-After
503	`service_unavailable`	The service is temporarily busy, for example because of database load.	yes, after Retry-After