> ## Documentation Index > Fetch the complete documentation index at: https://docs.dify.ai/llms.txt > Use this file to discover all available pages before exploring further. # List Sources > Lists the sources of a knowledge base in ascending source ID order, with each source's sync schedule, its last completed sync or import, and its current run, or its latest sync when none is running. A source leaves this listing as soon as its deletion is accepted. For how to start and follow a sync, see [Sync and Schedule Sources](/en/api-reference/guides/knowledge-base#sync-and-schedule-sources). ## OpenAPI ````yaml /en/api-reference/openapi_service.json get /knowledge-fs/spaces/{knowledge_base_id}/sources openapi: 3.0.1 info: description: >- REST API for Dify applications and knowledge bases. Application endpoints authenticate with an app API key; knowledge endpoints authenticate with a dataset API key. title: Dify Service API version: 1.0.0 servers: - description: >- Base URL of the Dify Service API. For self-hosted deployments, replace it with your own API base URL. url: https://{api_base_url} variables: api_base_url: default: api.dify.ai/v1 description: Host and path of the API base URL, without the `https://` prefix. security: - ApiKeyAuth: [] tags: - description: Operations related to chat messages and interactions. name: Chat Messages - description: File upload and preview operations. name: Files - description: Operations related to end user information. name: End Users - description: User feedback operations. name: Feedback - description: Operations related to managing conversations. name: Conversations - description: Text-to-Speech and Speech-to-Text operations. name: Audio - description: Operations to retrieve application settings and information. name: Applications - description: Operations related to managing annotations for direct replies. name: Annotations - description: Endpoints for resuming paused workflows that require human input. name: Human Input - description: Operations for executing and managing workflows. name: Workflow Runs - description: Operations related to text generation and completion. name: Completion Messages - description: >- Operations for managing knowledge bases, including creation, configuration, and retrieval. name: Knowledge Bases - description: >- Operations for creating, updating, and managing documents within a knowledge base. name: Documents - description: Operations for managing document chunks and child chunks. name: Chunks - description: >- Operations for managing knowledge base metadata fields and document metadata values. name: Metadata - description: Operations for managing knowledge base tags and tag bindings. name: Tags - description: Operations for retrieving available models. name: Models - description: >- Operations for managing and running knowledge pipelines, including datasource plugins and pipeline execution. name: Knowledge Pipeline - description: Ask a knowledge base a question and stream the answer. name: Queries - description: Inspect what a query retrieved and why. name: Query Records - description: Run a research question in the background and collect its results. name: Research Tasks - description: >- Read the documents in a knowledge base, their files, revisions, and chunks; label documents with metadata. name: Documents and Chunks - description: >- Follow, cancel, or retry indexing, and list the knowledge base's background tasks. name: Indexing Tasks - description: >- Follow the deletion of a document file, a batch of files, or a source until it finishes. name: Deletion Jobs - description: >- Manage the sources that feed a knowledge base, their sync schedules, and their connections. name: Sources - description: >- Sync a source now, import website pages or provider items, and follow, cancel, or retry the runs. name: Source Syncs and Imports - description: >- Read and change the knowledge base's models and retrieval settings, and follow the migration a change starts. name: Settings paths: /knowledge-fs/spaces/{knowledge_base_id}/sources: get: tags: - Sources summary: List Sources description: >- Lists the sources of a knowledge base in ascending source ID order, with each source's sync schedule, its last completed sync or import, and its current run, or its latest sync when none is running. A source leaves this listing as soon as its deletion is accepted. For how to start and follow a sync, see [Sync and Schedule Sources](/en/api-reference/guides/knowledge-base#sync-and-schedule-sources). operationId: listSources parameters: - description: >- Knowledge base ID: the last segment of the Service API endpoint shown in the knowledge base's **API Access** dialog (`…/knowledge-fs/spaces/`), and the segment after `/datasets/new/` in the address bar. in: path name: knowledge_base_id required: true schema: format: uuid type: string - description: Cursor from the previous page's `next_cursor`. in: query name: cursor required: false schema: maxLength: 1000 minLength: 1 type: string - description: Sources per page. in: query name: limit required: false schema: default: 50 maximum: 100 minimum: 1 type: integer responses: '200': content: application/json: examples: success: summary: Response Example value: data: - connection_id: c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f created_at: '2026-09-01T08:00:00Z' credential_configured: null id: 6f1c2b0e-3d0b-4a5e-9f4c-1c0e6a7b8d90 knowledge_space_id: 0a9d3c2e-5b6f-4e1a-8c7d-2f3e4a5b6c7d last_synced_at: '2026-09-05T10:12:00Z' metadata: client_request_id: source-20260907-0001 providerKind: website tenantId: 2f1e0d9c-8b7a-4695-8473-2a1b0c9d8e7f name: Docs site permission_scope: [] status: active sync_policy: created_at: '2026-09-01T08:05:00Z' custom_interval_seconds: null enabled: true expected_source_version: 7 id: 8e7d6c5b-4a39-4f28-9e17-0d1c2b3a4f5e knowledge_space_id: 0a9d3c2e-5b6f-4e1a-8c7d-2f3e4a5b6c7d mode: interval next_run_at: '2026-09-06T10:00:00Z' revision: 2 source_id: 6f1c2b0e-3d0b-4a5e-9f4c-1c0e6a7b8d90 updated_at: '2026-09-05T10:00:00Z' sync_workflow: canceled_at: null checkpoint: source-committed completed_at: '2026-09-05T10:12:00Z' created_at: '2026-09-05T10:00:00Z' cursor: >- ss1:eyJmaW5nZXJwcmludCI6IjgxZDk5OWY4YjI4ZDZhMGFlMTVmNjQxYzE2NjE3ZWNlMTBjYTcxMzE3OWU1MmVhMTYwODYyMzExMDcyYmQ4YmUiLCJraW5kIjoid2Vic2l0ZSIsIm9mZnNldCI6MCwicGhhc2UiOiJlb2YiLCJwcm9ncmVzc0NvbXBsZXRlZCI6NDUsInByb2dyZXNzVG90YWwiOjQ1fQ execution_attempts: 1 failure: null id: d4c3b2a1-6f5e-4d7c-8b9a-0f1e2d3c4b5a kind: sync knowledge_space_id: 0a9d3c2e-5b6f-4e1a-8c7d-2f3e4a5b6c7d last_error_code: null max_execution_attempts: 5 progress_completed: 45 progress_failed: 0 progress_skipped: 0 progress_total: 45 source_id: 6f1c2b0e-3d0b-4a5e-9f4c-1c0e6a7b8d90 state: completed updated_at: '2026-09-05T10:12:00Z' type: web updated_at: '2026-09-03T09:20:00Z' uri: https://docs.example.com version: 7 next_cursor: null schema: properties: data: description: Sources on this page. items: $ref: '#/components/schemas/KnowledgeBaseSource' type: array next_cursor: description: >- Cursor for the next page, or `null` on the last page. Send it back as `cursor`. nullable: true type: string type: object description: One page of sources. '400': content: application/json: examples: knowledge_fs_invalid_request: summary: knowledge_fs_invalid_request value: code: knowledge_fs_invalid_request message: Agent Knowledge Base request is invalid. status: 400 violations: - field: - limit type: less_than_equal description: >- - `knowledge_fs_invalid_request`: `cursor` is empty or longer than 1,000 characters, `limit` is outside 1 to 100, or the query string carries an unsupported parameter. `violations` names each failing field. '401': content: application/json: examples: knowledge_fs_invalid_credential: summary: knowledge_fs_invalid_credential value: code: knowledge_fs_invalid_credential message: Invalid Agent Knowledge Base service credential. status: 401 unauthorized: summary: unauthorized value: code: unauthorized message: Access token is invalid status: 401 description: >- - `unauthorized`: the `Authorization` header is missing, or the key is unknown or not a knowledge base API key. - `knowledge_fs_invalid_credential`: the key is valid, but no knowledge base with this ID exists in the key's workspace, or the key is not tied to a workspace. '403': content: application/json: examples: forbidden: summary: forbidden (rate limit) value: code: forbidden message: >- Sorry, you have reached the knowledge base request rate limit of your subscription. status: 403 knowledge_fs_access_denied: summary: knowledge_fs_access_denied (key scope) value: code: knowledge_fs_access_denied message: Agent Knowledge Base operation is not allowed. status: 403 knowledge_fs_access_denied_upstream: summary: knowledge_fs_access_denied value: code: knowledge_fs_access_denied failure: action: contact_admin category: authorization code: KNOWLEDGE_FS_ACCESS_DENIED message: >- You do not have permission to perform this Agent Knowledge Base operation. retryPolicy: never message: >- You do not have permission to perform this Agent Knowledge Base operation. status: 403 description: >- - `knowledge_fs_access_denied`: the key is scoped to other knowledge bases, **API access** is off for this knowledge base, or the knowledge base is not active. - `knowledge_fs_access_denied`: the key has no access to this knowledge base's content. - `forbidden`: on Dify Cloud, the workspace has reached the knowledge base request rate limit of its subscription. Every call counts, reads included. '404': content: application/json: examples: knowledge_fs_resource_not_found: summary: knowledge_fs_resource_not_found value: code: knowledge_fs_resource_not_found failure: category: not_found code: KNOWLEDGE_FS_NOT_FOUND message: >- The requested Agent Knowledge Base resource was not found. retryPolicy: never message: The requested Agent Knowledge Base resource was not found. status: 404 not_found: summary: not_found (feature off) value: code: not_found message: >- The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again. status: 404 description: >- - `knowledge_fs_resource_not_found`: the knowledge base ID isn't recognized. - `not_found`: the Agent Knowledge Base feature is turned off on this deployment. '502': content: application/json: examples: knowledge_fs_upstream_unavailable: summary: knowledge_fs_upstream_unavailable value: code: knowledge_fs_upstream_unavailable message: Agent Knowledge Base is unavailable. status: 502 description: >- - `knowledge_fs_upstream_unavailable`: no answer came back in time, or the answer couldn't be read. Retry after a pause. '503': content: application/json: examples: knowledge_fs_operation_unavailable: summary: knowledge_fs_operation_unavailable value: code: knowledge_fs_operation_unavailable message: Agent Knowledge Base operation is not available. status: 503 knowledge_fs_operation_unavailable_upstream: summary: knowledge_fs_operation_unavailable (temporary) value: code: knowledge_fs_operation_unavailable failure: action: retry category: dependency code: KNOWLEDGE_FS_UNAVAILABLE message: >- A service required by Agent Knowledge Base is temporarily unavailable. retryPolicy: manual traceId: 5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b message: >- A service required by Agent Knowledge Base is temporarily unavailable. status: 503 description: >- - `knowledge_fs_operation_unavailable`: the Agent Knowledge Base feature is not set up for this workspace, this operation is not available on the deployment, or the key's access to this knowledge base changed while the request was being authorized. - `knowledge_fs_operation_unavailable`: the request can't be served right now. Follow `failure.retryPolicy`. - `knowledge_fs_operation_unavailable`: the request could not fill a page of sources this key can read. components: schemas: KnowledgeBaseSource: properties: connection_id: description: >- Connection the source uses for credentials. Pass it as `connectionId` when binding another source to the same connection. `null` when unbound. nullable: true type: string created_at: description: Creation time, ISO 8601. type: string credential_configured: description: >- `true` when the source holds a credential reference of its own. `null` when it holds none, as with sources bound to a connection. nullable: true type: boolean id: description: Source ID. type: string knowledge_space_id: description: >- Internal ID of the knowledge base. Not the knowledge base ID in the path. type: string last_synced_at: description: >- Completion time of the latest completed sync (`completed` or `zero_results`) or completed import. Set by [List Sources](/en/api-reference/sources/list-sources) only. `null` elsewhere and when the source has never synced. nullable: true type: string metadata: description: >- Provider settings and server-managed sync or page-selection data. May include provider identifiers and `parameters`; connection-managed settings need not appear here. Credential-like keys are removed. Do not copy the entire object when creating another source. type: object name: description: Display name. type: string permission_scope: description: >- Content scopes required to read this source. An empty list adds no content restriction within the knowledge base. Knowledge base authorization still applies. items: type: string type: array status: description: >- `active`, `syncing`, `error`, or `disabled`. Most operations return the stored value. [List Sources](/en/api-reference/sources/list-sources) derives it from the latest sync run: - `failed` or `canceled` run: `error` - `completed` or `zero_results` run: `active` - Any live run: `syncing` `disabled` is never overridden. type: string sync_policy: allOf: - $ref: '#/components/schemas/KnowledgeBaseSyncPolicy' description: >- The source's sync schedule. Set by [List Sources](/en/api-reference/sources/list-sources) only. `null` elsewhere and when no schedule exists. Read it on its own with [Get Sync Policy](/en/api-reference/sources/get-sync-policy) and change it with [Update Sync Policy](/en/api-reference/sources/update-sync-policy). nullable: true sync_workflow: allOf: - $ref: '#/components/schemas/KnowledgeBaseSourceRun' description: >- The source's active sync or import run (`crawl-import`, `online-document-import`, or `online-drive-import`), or else its latest sync run. [List Sources](/en/api-reference/sources/list-sources) sets it when a run is active or newer than the source. [Update Source](/en/api-reference/sources/update-source) sets it when the call started a sync. `null` otherwise. Crawl previews and imports from them never appear here. To follow one run, call [Get Source Run](/en/api-reference/source-syncs-and-imports/get-source-run) with its `id`. nullable: true type: description: >- `web` (website crawl), `connector` (online document or online drive), `upload`, or `object-storage`. For a `connector` source, `metadata.providerKind` is `online-document` or `online-drive`. For a `web` source it is `website`. Dify fills `upload` and `object-storage` sources. type: string updated_at: description: Last change, ISO 8601. type: string uri: description: >- Crawl root URL for `web` sources. `connector://` for Dify-created connector sources. type: string version: description: >- Source version, increased on every write. Send it as `expectedVersion` on [Update Source](/en/api-reference/sources/update-source), as `expectedRevision` on [Delete Source](/en/api-reference/sources/delete-source), and as `expectedSourceVersion` on [Update Sync Policy](/en/api-reference/sources/update-sync-policy). type: integer type: object KnowledgeBaseSyncPolicy: properties: created_at: description: Creation time, ISO 8601. type: string custom_interval_seconds: description: 'Interval in seconds for `mode: custom`. `null` for the other modes.' nullable: true type: integer enabled: description: 'Whether scheduled syncs run. Always `false` with `mode: manual`.' type: boolean expected_source_version: description: Source `version` the schedule is bound to. type: integer id: description: Sync policy ID. It stays the same across updates. type: string knowledge_space_id: description: >- Internal ID of the knowledge base. Not the knowledge base ID in the path. type: string mode: description: >- `manual` (no schedule), `interval` (every 24 hours), or `custom` (every `custom_interval_seconds`). type: string next_run_at: description: >- When the next scheduled sync is due, ISO 8601. `null` when nothing is scheduled. nullable: true type: string revision: description: >- Schedule revision. Send it as `expectedRevision` on [Update Sync Policy](/en/api-reference/sources/update-sync-policy). It increases on every update and every time a scheduled sync starts. type: integer source_id: description: Source the schedule belongs to. type: string updated_at: description: Last change, ISO 8601. Also moves when a scheduled sync starts. type: string type: object KnowledgeBaseSourceRun: properties: canceled_at: description: When the run was canceled. `null` unless `state` is `canceled`. nullable: true type: string checkpoint: description: >- Last step the run reached: `queued`, `provider-read`, `preview-staged`, `selection-frozen`, `materialized`, `cleanup-staging`, or `source-committed`. [Retry Source Run](/en/api-reference/source-syncs-and-imports/retry-source-run) starts the run over whatever its checkpoint. type: string completed_at: description: >- When the run ended (`completed`, `zero_results`, `failed`, or `canceled`), ISO 8601. `null` while it runs. nullable: true type: string created_at: description: Creation time, ISO 8601. type: string cursor: description: >- Provider cursor the run resumes from. `null` when the run has not paged. nullable: true type: string execution_attempts: description: >- Times a worker has picked up the run, including after [Retry Source Run](/en/api-reference/source-syncs-and-imports/retry-source-run), which does not reset it. type: integer failure: allOf: - $ref: '#/components/schemas/KnowledgeBaseErrorDetails' description: >- Error details when `state` is `failed`. `stage` is the run's `checkpoint` at the failure, and `traceId` is the run ID. `null` otherwise. nullable: true id: description: >- Run ID. Pass it to [Get Source Run](/en/api-reference/source-syncs-and-imports/get-source-run), [Cancel Source Run](/en/api-reference/source-syncs-and-imports/cancel-source-run), or [Retry Source Run](/en/api-reference/source-syncs-and-imports/retry-source-run). type: string kind: description: >- What the run does: - `sync`: started by [Sync Source](/en/api-reference/source-syncs-and-imports/sync-source), [Update Source](/en/api-reference/sources/update-source), a schedule, or Dify. - `crawl-preview`: started by [Preview Website Crawl](/en/api-reference/source-syncs-and-imports/preview-website-crawl). It keeps this kind while [Import Selected Pages](/en/api-reference/source-syncs-and-imports/import-selected-pages) imports from it. - `crawl-import`: started by [Import Website Pages](/en/api-reference/source-syncs-and-imports/import-website-pages). - `online-document-import`, `online-drive-import`: started by [Import Source Items](/en/api-reference/source-syncs-and-imports/import-source-items). Dify also starts previews and imports when a source is added or edited there. type: string knowledge_space_id: description: >- Internal ID of the knowledge base. Not the knowledge base ID in the path. type: string last_error_code: description: '`failure.code` when `state` is `failed`. `null` otherwise.' nullable: true type: string max_execution_attempts: description: >- Limit on `execution_attempts`. Once it is reached, [Retry Source Run](/en/api-reference/source-syncs-and-imports/retry-source-run) answers `409`. type: integer progress_completed: description: Items finished, including unchanged items a sync checked. type: integer progress_failed: description: 'Always `0` for source runs: a failing item fails the whole run.' type: integer progress_skipped: description: Always `0` for source runs. type: integer progress_total: description: >- Items the run expects to process: the pages or items an import requested, the pages a crawl preview has staged so far, or the source's items once a sync has listed them. `null` until known. While an [Import Website Pages](/en/api-reference/source-syncs-and-imports/import-website-pages) run crawls its URLs, `progress_completed` and `progress_total` both count the pages crawled so far. Once every URL is crawled, they restart at `0` of the number of URLs. nullable: true type: integer source_id: description: Source the run belongs to. nullable: true type: string state: description: >- Progress of the run. Live states: - `queued`: waiting for a worker - `crawling`: a crawl preview is fetching pages - `preview_ready`: a crawl preview is waiting for [Import Selected Pages](/en/api-reference/source-syncs-and-imports/import-selected-pages) or [Cancel Source Run](/en/api-reference/source-syncs-and-imports/cancel-source-run) - `importing`: importing and indexing items - `syncing`: refreshing the source's documents Terminal states: - `completed`: every item was imported or refreshed, indexed, and made active - `zero_results`: a crawl preview found no pages - `failed`: see `failure` - `canceled` After `failed` or `canceled`, [Retry Source Run](/en/api-reference/source-syncs-and-imports/retry-source-run) runs it again, and [Sync Source](/en/api-reference/source-syncs-and-imports/sync-source) starts a new sync. type: string updated_at: description: Last change, ISO 8601. type: string type: object KnowledgeBaseErrorDetails: properties: action: description: >- Suggested next step, when there is one: `configure_model`, `configure_parser`, `configure_source`, `contact_admin`, `reupload`, or `retry`. `null` when not applicable; omitted from HTTP error bodies. nullable: true type: string category: description: >- Kind of failure: `authorization`, `canceled`, `configuration`, `conflict`, `dependency`, `internal`, `not_found`, `rate_limit`, `timeout`, or `validation`. type: string code: description: >- Stable error code in upper snake case, for example `KNOWLEDGE_FS_CONFLICT` or `SOURCE_CREDENTIAL_TEST_FAILED`. type: string message: description: >- Public message for the error code or failure category. Provider error details are not exposed. type: string parameters: additionalProperties: true description: >- Up to 8 values that qualify the failure, with keys among `attempt`, `currentRowVersion`, `documentCount`, `expectedRowVersion`, `fileSizeBytes`, `limit`, `maxFileSizeBytes`, `maxItems`, `modelType`, `providerKind`, `retryAfterSeconds`, and `status`. `null` when there are none; omitted from HTTP error bodies. nullable: true type: object retryPolicy: description: >- Whether a retry can help: `automatic` (the service retries on its own), `manual` (retry yourself), `after_configuration` (fix the knowledge base's setup in Dify first), or `never` (change the request). type: string stage: description: >- Stage the failure belongs to, for example `query_generation` or `credential-test`. `null` when not applicable; omitted from HTTP error bodies. nullable: true type: string traceId: description: >- Reference to quote when contacting an administrator. May be `null` in a successful response containing failure details, or omitted from an HTTP error body. nullable: true type: string type: object securitySchemes: ApiKeyAuth: bearerFormat: API_KEY description: >- Every request authenticates with an API key: `Authorization: Bearer {API_KEY}`. App endpoints take an app API key; knowledge endpoints take a knowledge base API key ([Get Started](/en/api-reference/guides/get-started)). Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP `401` (`unauthorized`). scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.