Skip to main content
Unstructured API
Unstructured API Quickstart - On-Demand Jobs
This quickstart shows how to use the Unstructured Python SDK
to have Unstructured process local files by using the Unstructured API’s on-demand jobs functionality. This functionality
is part of the Unstructured API’s collection of workflow operations.
On-demand jobs take one or more local files as input. Unstructured outputs the local files’ contents as a series of Unstructured
document elements and metadata. This format is ideal for retrieval-augmented generation (RAG),
agentic AI, and model fine-tuning.
The on-demand jobs functionality is designed to work only by processing local files.To process files (and data) in remote file and blob storage, databases, and vector stores, you must use other
workflow operations in the Unstructured API. To learn how, see for example the notebook
Dropbox-To-Pinecone Connector API Quickstart for Unstructured.
Requirements
To run this quickstart, you will need:-
An Unstructured account. If you do not already have an Unstructured account, sign up for free.
After you sign up, you are immediately signed in to your new Let’s Go account, at https://platform.unstructured.io.
If you already have an Unstructured Pay-As-You-Go or Business SaaS account, you are already signed up for Unstructured. Sign in to your existing Unstructured Pay-As-You-Go or Business SaaS account, at https://platform.unstructured.io.If you already have an Unstructured dedicated instance or in-VPC deployment, your sign-in link will be unique to your deployment. If you’re not sure what your unique sign-in link is, see your Unstructured account administrator, or email Unstructured Support at support@unstructured.io.
-
An Unstructured API key, as follows:
-
After you are signed in to your account, on the sidebar click API Keys.
For a Business account, before you click API Keys, make sure you have selected the organizational workspace you want to create an API key for. Each API key works with one and only one organizational workspace. Learn more.
- Click Generate New Key.
- Enter some meaningful display name for the key, and then click Continue.
- Next to the new key’s name, click the Copy icon. The key’s value is copied to your system’s clipboard. If you lose this key, simply return to the list and click Copy again.
-
After you are signed in to your account, on the sidebar click API Keys.
- Python 3.9 or higher installed on your local machine.
-
A Python virtual environment is recommended for isolating and versioning Python project code dependencies on your local machine,
but this is not required. This quickstart uses the popular Python package and project manager uv
for managing virtual environments. Installation and use of
uvare described in the following steps. -
One or more local files for Unstructured to process. The following code example assumes that the local files
you want to process are in a folder named
input, which is in the same project directory as your Python code. Creation of this folder is described in the following steps. The files’ types must be in the list of supported file types.Each on-demand job is limited to 10 files, and each file is limited to 10 MB in size.If you need to launch a series of on-demand jobs in rapid succession, you must wait at least one second between launch requests. Otherwise, you will receive a rate limit error.A maximum of 5 on-demand jobs can be running in your Unstructured account. If you launch a new on-demand job but 5 existing on-demand jobs are still running, the new on-demand job will remain in a scheduled state until one of the 5 existing on-demand jobs is done running. -
A destination folder for Unstructured to send its processed results to. The following code example assumes that the
destination folder is named
outputand is in the same project directory as your Python code. Creation of this folder is described in the following steps.
Step 1: Create a Python virtual environment
In this step, you useuv to create a new Python project, and a virtual environment within this project, for this quickstart.
If you do not want to use
uv or create a Python project, you can do the following instead:-
Install the Unstructured Python SDK globally on your local machine by running the following command:
- Skip ahead to Step 2.
- Install uv on your local machine, if it is not already installed.
-
Create a new, blank folder on your local machine for this quickstart, and then switch to this new folder.
This example creates a folder named
unstructured_api_quickstartwithin your current working directory and then switches to this new folder: -
Create a new
uvproject for this quickstart by running the following command from within the new folder: -
Create a new virtual environment within this project by running the following command:
-
Activate the virtual environment by running the following command:
-
Install the Unstructured Python SDK into the virtual environment, by running the following commands:
Step 2: Add the example code
-
In the same directory as the project’s
main.pycode file, add two folders namedinputandoutput. Your project directory should now look like this:If you do not want to useuvor create a Python project, just create a blank file namedmain.pyand two folders namedinputandoutputthat are all in the same local directory instead, for example: -
Upload the files you want Unstructured to process into the new
inputfolder. -
Overwrite the contents of the
main.pyfile with the following code. In this code, replace<your-unstructured-api-key>(in themain()function, near the end of the following code) with the value of your Unstructured API key. Then save this file.
Step 3: Run the code and view the results
Each on-demand job is limited to 10 files, and each file is limited to 10 MB in size.If you need to launch a series of on-demand jobs in rapid succession, you must wait at least one second between launch
requests. Otherwise, you will receive a rate limit error.A maximum of 5 on-demand jobs can be running in your Unstructured account. If you launch a new on-demand job
but 5 existing on-demand jobs are still running, the new on-demand job will remain in a scheduled state until one of the 5
existing on-demand jobs is done running.
-
Run the code in the
main.pyfile, by running the following command:If you do not want to useuvor create a Python project, you can run the code by running the following command instead: -
After the code finishes running, look in the
outputfolder to see Unstructured’s results.


