# List files URL: https://docs.hanzo.ai/docs/openapi/knowledge/get-knowledge-files > Answers the caller's org files, most recently changed first, each with its status and stage — optionally only those in one bucket, which is how Drive shows a folder's files with their index state. `GET /v1/knowledge/files` > [Knowledge →](https://docs.hanzo.ai/docs/openapi/knowledge) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides) | | | | ------------- | ----------------------------------------- | | **Address** | `https://api.hanzo.ai/v1/knowledge/files` | | **Method** | `GET` | | **Operation** | `get_knowledge_files` | | **Auth** | `Authorization: Bearer $HANZO_API_KEY` | Answers the caller's org files, most recently changed first, each with its status and stage — optionally only those in one bucket, which is how Drive shows a folder's files with their index state. ## Request 2 fields. | Field | In | Type | Required | Description | | -------- | ----- | ------ | -------- | ----------- | | `bucket` | query | string | — | | | `limit` | query | string | — | | ## Response | Status | Body | Meaning | | --------- | ------------------ | ------- | | `200` | knowledge.filesOut | ok | | `default` | problem-details | refused | `200` body — 22 fields. | Field | In | Type | Always | Description | | ------------------ | ---- | ----------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `files` | body | knowledge.File\[] | — | Files are the org's files, most recently changed first. | | `files[].bucket` | body | string | — | Bucket is the org bucket the object is in, by the friendly name /v1/s3/buckets lists. | | `files[].chars` | body | integer (int64) | — | Chars is the length of the text read out of the file, in bytes. | | `files[].clipped` | body | boolean | — | Clipped is true when only the file's beginning is indexed: its text ran past the org's bound or the room the index has. | | `files[].created` | body | integer (int64) | — | Created is when the file was first registered, in unix seconds. | | `files[].done` | body | integer (int64) | — | Done is how far the running stage has come, of Total: bytes of the file read (extract), sections summarized (toc), cut into passages (passages) and linked (graph), passages embedded (embed). | | `files[].embedded` | body | integer (int64) | — | Embedded is how many of those passages carry a vector — Passages once the embed stage is done, unless Note says the file is embedded in part. | | `files[].error` | body | string | — | Error is why a stored or failed file was not indexed — or, on a ready file, why it is searched by its words alone — in words a person can act on. | | `files[].id` | body | string | — | ID names the file in its org. | | `files[].key` | body | string | — | Key is the object's key in that bucket. | | `files[].name` | body | string | — | Name is the object's file name, the last segment of its key. | | `files[].note` | body | string | — | Note says in words where the file is indexed less than whole and why: its text past the org's bound or the room the index has, its passages past the bound on vectors. | | `files[].parent` | body | string | — | Parent is the id of the archive this file was unpacked from. | | `files[].passages` | body | integer (int64) | — | Passages is how many passages its text was cut into. | | `files[].project` | body | string | — | Project is the project scope it is indexed under. | | `files[].sections` | body | integer (int64) | — | Sections is how many nodes its table of contents has, the document's own root included. | | `files[].size` | body | integer (int64) | — | Size is the object's length in bytes, as the store reports it. | | `files[].stage` | body | string | — | Stage is the ingest stage the file is in: extract, toc, passages or graph while indexing, embed while a ready file's vectors are written. | | `files[].status` | body | string | — | Status is queued, indexing, ready, stored (kept but not indexed — Error says why) or failed. | | `files[].total` | body | integer (int64) | — | Total is what the running stage has to do in all, in Done's units. | | `files[].type` | body | string | — | Type is the object's media type as the store holds it, or the one its name implies when the store holds only the generic default. | | `files[].updated` | body | integer (int64) | — | Updated is when its record last changed, in unix seconds. | Failure carries the platform error shape — see [Errors](https://docs.hanzo.ai/docs/errors). ## Examples **CLI** `hanzo` has no subcommand for this operation — the CLI serves only what cloud's live route table confirms. Use HTTP or an SDK. **SDK** **.ts** ```ts import { Configuration, KnowledgeApi } from 'hanzoai'; const api = new KnowledgeApi(new Configuration({ accessToken: process.env.HANZO_API_KEY })); const { data } = await api.getKnowledgeFiles(); ``` **.py** ```python from hanzoai.cloud import ApiClient, Configuration from hanzoai.cloud.api import KnowledgeApi client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"])) result = KnowledgeApi(client).get_knowledge_files() ``` **.go** ```go cfg := hanzoai.NewConfiguration() cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY")) client := hanzoai.NewAPIClient(cfg) resp, _, err := client.KnowledgeAPI.GetKnowledgeFiles(context.Background()).Execute() if err != nil { return err } ``` **.rs** ```rust use hanzo_client::apis::{configuration::Configuration, knowledge_api}; let mut cfg = Configuration::new(); cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok(); let result = knowledge_api::get_knowledge_files(&cfg, Default::default()).await?; ``` **.java** ```java import ai.hanzo.cloud.ApiClient; import ai.hanzo.cloud.api.KnowledgeApi; ApiClient client = new ApiClient(); client.setBearerToken(System.getenv("HANZO_API_KEY")); var result = new KnowledgeApi(client).getKnowledgeFiles(); ``` **HTTP** ```bash curl https://api.hanzo.ai/v1/knowledge/files \ -H "Authorization: Bearer $HANZO_API_KEY" ``` **MCP** MCP reaches **knowledge** through the `knowledge` tool, which names its 9 operations with its own verbs — this one among them, under a name only MCP declares. `describe` explains any of them: ```bash curl -X POST https://api.hanzo.ai/v1/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "describe", "arguments": { "op": "list_knowledge_connectors" } } }' ``` --- [Knowledge API](https://docs.hanzo.ai/docs/openapi/knowledge) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)