--- title: "Library limits for sizing files, batches, and storage plans" description: "Library limits define file size, format support, API ceilings, time windows, and metering for sizing files, batches, and storage plans." lang: en status: public-preview lastUpdated: 2026-09-04 url: https://duale.ai/en/docs/libraries/limits --- ## AI-generated summary Library limits groups the file-size, path, tags, call-ceiling, window, processing, and metering numbers a customer uses to size a Library and plan uploads. - One file is 500 MiB at most; split larger sources into separate documents. - Upload sessions last 24 hours and part URLs last 6 hours; act before each expires. - The platform allows 30 minutes to extract one document and 15 minutes per searchable part. - Deleted documents count toward storage for 30 days before asynchronous removal. - list_documents takes a limit of 1 to 500 with a cursor for the next response. Summaries were generated by AI. Generative AI is experimental. --- Use this page to size a file, a corpus, a batch, or a storage plan. It groups the Library limits that affect those decisions by the question that sends you looking for them. Some limits are part of the versioned API contract. Changing them breaks clients. Other limits are service settings that a release can change. | Class | Limits | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | Versioned API contract | `path` length, `list_documents` page size, and the Find, Match, List, and Read ceilings | | Release setting | `tags` size, file-size cap, format list, upload-session lifetime, upload part-URL lifetime, deletion windows, and processing allowances | ## What one file can be One file can be 500 MiB at most, and its file type must be one the platform reads. Split a larger source and upload each part as its own document. The platform reads 143 file extensions in 9 categories. These counts were verified on 2026-08-31: | Category | Extensions | | ------------- | ---------- | | Documents | 25 | | Spreadsheets | 10 | | Presentations | 4 | | Images | 20 | | Videos | 11 | | Email | 4 | | Subtitles | 9 | | Data | 4 | | Code | 56 | Two notes on what that list covers, and two boundaries: - Documents include `.pdf`, `.docx`, `.doc`, `.rtf`, `.odt`, `.epub`, `.html`, `.md`, `.txt`, `.tex`, `.pages`, `.xps`, `.cbz`, `.mhtml`, and 11 more extensions. - Data covers `.xml`, `.json`, `.jsonl`, and `.ndjson`. Code covers 56 extensions. - From a video the platform reads the text that is visible in the frames. It does not read the speech. - The platform reads text, so a recording enters a Library as a transcript or as a subtitle file. Subtitles cover `.srt`, `.vtt`, and seven more extensions. `GET {DUALE_ENDPOINT}/libraries/v1/tenants/{tenant_id}/document-uploads/supported-formats` returns the exact advertised extension list and is the authority for a file picker. The route checks the `library:upload` action, its response is cacheable, and the list changes only with a release. Read the route before a large import; the counts above are orientation for the date they name. ## What a Library can hold Two values bound a Library: its `path` length and its `tags` size. Nothing caps the documents in a Library or the Libraries in a tenant, so size a Library around the agent that reads it, not around a count. | Limit | Value | Your action | | ------------------------ | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | `path` | 1 to 300 characters, free-form | Address a Library by its identifier. A path is display metadata, and two Libraries can carry the same one. | | `tags` | 4 KiB of serialized JSON, on a Library and on each document | Keep each value a string, an integer, a number, or a boolean. An update replaces the complete map. | | Documents in one Library | No ceiling | Split a corpus by the question it answers, not by a document count. | | Libraries per tenant | No ceiling | Design around reader groups, not a count. `list()` below bounds what one caller can reach. | ## What one call returns Every listing and every document tool returns a bounded result. The model's four document tools run under ceilings that your code does not pass: | Tool | Ceiling for one call | Name you see in a trace | | --------- | ------------------------------------------------------ | ----------------------- | | **Find** | 100 results, 20 by default | `file_search` | | **Match** | 500 matches, 100 by default, and 0 to 20 context lines | `file_grep` | | **List** | 500 documents in one response | `file_ls` | | **Read** | One document | `file_cat` | Your own code passes none of those numbers. The model chooses a tool during a task, and the platform applies the ceiling. [What agents can do with a Library](https://duale.ai/en/docs/libraries/what-agents-can-do.md) explains what each tool matches, why a trace name is not an API, and how to read an answer that stopped early. Two numbers belong to your own code instead: - `list_documents(request)` takes a `limit` of 1 to 500 and returns that many documents in one response, with a cursor for the next response. Pass each cursor back until `next_cursor` is `None`. - `list()` returns the Libraries the caller can read. When the caller can reach 5,000 resources, the call raises an error instead of returning a partial list. The platform exposes no counter for that set. Treat the error as the signal: split the caller's work across agent identities with narrower Library grants, then retry. [SDK reference](https://duale.ai/en/docs/sdk/reference.md) states both signatures and the exception type, and [Access and isolation](https://duale.ai/en/docs/libraries/access.md) states who grants the actions that a caller resolves. ## How long each window lasts Four windows govern incomplete uploads and deletion. Act before each one ends. | Window | Duration | What happens at the end | | ------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------- | | Upload session | 24 hours | The session expires. Start a new upload for a file whose parts did not all arrive. | | Upload part URL | 6 hours | The URL stops working. A large file over a slow connection can reach that window, so upload every part inside it. | | Recently deleted, per document | 30 days | The document becomes eligible for asynchronous removal after the window. Restore it from the Dashboard inside it. | | Deleted Library | 24 hours | The record and grants become eligible for asynchronous removal. A deleted Library cannot be restored. | Nothing removes a document permanently inside its 30-day window unless you delete its Library. Deleting that Library also deletes the document, even while it is in Recently deleted. [Security and data handling](https://duale.ai/en/docs/libraries/security.md) covers what the platform does with a document between the delete and the removal. ## How long processing takes The SDK's polling helper stops after 360 seconds by default, before the platform's processing allowance can end. A client timeout does not prove that processing failed. Pass a longer `timeout=` for a large file, then read the returned status instead of uploading the file a second time. The platform allows 30 minutes to extract one document and 15 minutes to make each part of its text searchable. A longer document has more parts, so do not compute a total wait from those two numbers. [Manage libraries](https://duale.ai/en/docs/sdk/manage-libraries.md) shows the polling call and the states a document moves through. Duale AI publishes no total time for a batch, and documents can finish in any order. Test a representative batch under your production conditions, then wait for every document the task needs to reach `ready`. ## What the platform meters The platform meters stored document volume over time. A document counts from when the platform stores it until the platform deletes it permanently. A deleted document stays in the 30-day Recently deleted window and still counts during that window. Delete it as soon as your retention policy allows. Include the 30 days in its cost. Nothing expires a Library that a task created for its attachments, so its documents count until you delete them. [Attach documents](https://duale.ai/en/docs/sdk/attachments.md) covers the files that one task carries. [Pricing and access](https://duale.ai/en/product/pricing.md) states how the order form fixes the storage rate and included volume. ### What a nightly refresh costs A nightly refresh that uploads every file and deletes the prior documents still holds about thirty superseded copies of every file, plus the current one. A change-only refresh keeps that extra volume to the files that changed. This happens because uploading a file again creates a new document instead of replacing the old one, and a document you delete keeps counting for its 30-day window. [Best practices](https://duale.ai/en/docs/libraries/best-practices.md) gives the habit that keeps a changing set of documents to roughly its own size. ## What Libraries do not do Libraries have eight current boundaries. Draw your design around them. | Boundary | What you do instead | | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | **No direct query.** Retrieval happens inside an agent task, and the Library API carries no search route. | Ask through a task. The agent runs List, Find, Match, and Read over the Libraries you granted it. | | **No read-back of what the agent retrieved.** Your code cannot see which passages an agent read. | Read a document preview, the only content read-back path. It returns the opening of a document's extracted text. | | **No query-time attribute filter.** The Library is the scope of a question. | Put the documents that answer one kind of question in one Library, then grant that Library to the agent that asks it. | | **No chunking, ranking, or relevance controls.** Nothing tunes retrieval per Library. | Shape the corpus instead. A relevance threshold you carry from another retrieval system does not transfer. | | **No scheduled sync, no connector, and no crawler.** Every document arrives by an upload you make. | Upload each change yourself, so the set an agent quotes is the set you shipped. | | **No speech transcription.** The platform reads text. | Upload a recording as a transcript or as a subtitle file. | | **No move between Libraries or between tenants.** A document belongs to the Library it entered. | Upload the file again into the Library or the tenant that needs it. | | **No guarantee that extraction is faithful.** Extraction is best effort, especially when meaning is visual. | For a document that has to be exactly right, [extract it yourself and upload the text](https://duale.ai/en/docs/libraries/patterns.md). | Read-back is the boundary behind every diagnosis. You cannot replay the passages an agent read, so you test a corpus with a question you know one document answers, then read the answer. [SDK reference](https://duale.ai/en/docs/sdk/reference.md) states the preview call, and [Best practices](https://duale.ai/en/docs/libraries/best-practices.md) gives one check for each habit. ## Related content - [How the platform protects and removes your documents](https://duale.ai/en/docs/libraries/security.md) - [Manage Libraries and documents with the SDK](https://duale.ai/en/docs/sdk/manage-libraries.md) - [The documents your agents can read](https://duale.ai/en/docs/libraries.md) - [Get better answers from a Library](https://duale.ai/en/docs/libraries/best-practices.md) - [Attach files to a task using the SDK](https://duale.ai/en/docs/sdk/attachments.md) - [Design your Libraries by reader group and agent reach](https://duale.ai/en/docs/libraries/design.md) --- ## Sitemap See the full [Markdown sitemap](https://duale.ai/sitemap.md) for all pages.