The Unstructured Serverless API is separate from the Unstructured Platform API.

For information about the Unstructured Platform API, see the Unstructured Platform API Overview.

This page describes how to get started with the Unstructured Serverless API. Learn how to obtain an API key to use with the Unstructured Serverless API, and get started in no time.

​
Get started

To call the Unstructured Serverless API, you need an Unstructured account, API key, and API URL:

1

Sign up

To sign up for an Unstructured account, go to the For Developers page and choose one of the following plans:

If you’re not sure which plan to sign up for, start with a pay-per-page plan. You can always switch plans later.

If you choose a pay-per-page plan, after your first 14 days of usage or more than 1000 processed pages per day, whichever comes first, your account is then billed at Unstructured’s standard service usage rates. To keep using the service, you must provide Unstructured with your payment details.

To save money by switching from a pay-per-page to a subscribe-and-save plan, go to the Unstructured Subscribe & Save page and complete the on-screen instructions.

By signing up for a pay-per-page or subscribe-and-save plan, your Unstructured account will run within the context of the Unstructured Platform on Unstructured’s own hosted cloud resources. If you would rather run the Unstructured Platform within the context of your own virtual private cloud (VPC), (or you want to save even more money by making a long-term billing commitment), stop here and sign up through the For Enterprise page instead.

2

Sign in

If you initially signed up for a subscribe-and-save plan instead of a pay-per-page plan, wait to complete this step until after you receive confirmation from Unstructured that your plan is activated. Then go to the Unstructured home page at https://unstructured.io and click Login.

If you signed up through the For Enterprise page instead, your sign-in process will be different. For enterprise sign-in guidance, contact Unstructured Sales at sales@unstructured.io.

  1. After you have signed up for a pay-per-page plan, the Unstructured Platform sign-in page appears.

  2. Click Google or GitHub to sign in with the Google or GitHub account that you signed up with. Or, enter the email address that you signed up with, and then click Sign In.

  3. If you entered your email address, check your email inbox for a message from Unstructured. In that email, click the Sign In link.

  4. The first time you sign in, read the terms and conditions, and then click Accept.

After you have signed in for the first time, you can sign in the second time and beyond by going to the Unstructured home page at https://unstructured.io and clicking Login.

For enterprise sign-in guidance, contact Unstructured Sales at sales@unstructured.io.

3

Get your API key and API URL

  1. After you have signed in to your Unstructured account, at the bottom of the sidebar, click your user icon, and then click Account Settings.
  2. On the API Keys tab, click Generate New Key.
  3. Enter some descriptive name for the API key, and then click Save.
  4. Click the Copy icon for your new API key. The API key’s value is copied to your system’s clipboard.
  5. Note the Unstructured Serverless API URL, which is https://api.unstructuredapp.io/general/v0/general

Do not use the Unstructured Platform API URL, which is separate from the Unstructured Serverless API URL.

If you signed up through the For Enterprise page, your API URL might be different. For API URL guidance, email Unstructured Sales at sales@unstructured.io. If your API URL is different, be sure to substitute https://api.unstructuredapp.io/general/v0/general for your API URL throughout the following examples.

Unstructured Serverless API keys do not work with the Free Unstructured API. If you try to use an Unstructured Serverless API key with a Free Unstructured API URL, the call will fail. Use your Unstructured Serverless API URL instead.

Try the quickstart.

​
Set up billing

If you signed up for a pay-per-page plan, you can enjoy a free 14-day trial with usage capped at 1000 pages per day.

If you initially signed up for a subscribe-and-save plan instead, of if you signed up through the For Enterprise page instead, your billing setup and terms will be different. For billing guidance, contact Unstructured Sales at sales@unstructured.io.

The free 14-day trial for the Unstructured Serverless API is different than the Free Unstructured API.

At the end of the 14-day free trial, or if you need to go past the trial’s page processing limits during the 14-day free trial, you must set up your billing information to keep using the Unstructured Serverless API:

  1. Sign in to the Unstructured Platform.
  2. At the bottom of the sidebar, click your user icon, and then click Account Settings.
  3. Click the Billing tab.
  4. Click Manage Payment Method, follow the on-screen instructions to enter or update your payment details, and then click Save card.

Your card is billed monthly based on your usage. The Billing page shows a billing overview for the current month and a list of your billing invoices.

You can save money by switching from a pay-per-page plan to a subscribe-and-save plan. To do this, go to the Unstructured Subscribe & Save page and complete the on-screen instructions.

We calculate a page as follows:

  • For these file types, a page is a page, slide, or image: .pdf, .pptx, and .tiff.
  • For .docx files that have page metadata, we calculate the number of pages based on that metadata.
  • For all other file types, we calculate the number of pages as the file’s size divided by 100 KB.
  • For non-file data, we calculate a page as 100 KB of incoming data to be processed.

​
Quickstart

These examples use your local machine. They send source (input) files from your local machine to the Unstructured Serverless API which delivers the processed data to a destination (output) location, also on your local machine. Data is processed on Unstructured-hosted compute resources.

​
Unstructured Ingest CLI

To work with the Unstructured Serverless API by using the Unstructured Ingest CLI, you will need to:

  • Install Python, and then install the CLI package:

    pip install unstructured-ingest

  • Set the following environment variables:

    • Set UNSTRUCTURED_API_KEY to your API key.
    • Set UNSTRUCTURED_API_URL to your API URL.

    Get your API key and API URL.

  • Have some compatible files on your local machine to be processed. See the list of supported file types. If you do not have any files available, you can download some from the example-docs folder in the Unstructured repo on GitHub.

Now, use the CLI to call the API, replacing:

  • <path/to/input> with the source (input) path to the directory on your local machine that contains the compatible files for Unstructured to process on its hosted compute resources.
  • <path/to/output> with the destination (output) path to the directory on your local machine that will contain the processed data that Unstructured returns from its hosted compute resources.
CLI
unstructured-ingest \
  local \
    --input-path <path/to/input> \
    --output-dir <path/to/output> \
    --partition-by-api \
    --api-key $UNSTRUCTURED_API_KEY \
    --partition-endpoint $UNSTRUCTURED_API_URL \
    --strategy hi_res \
    --additional-partition-args="{\"split_pdf_page\":\"true\", \"split_pdf_allow_failed\":\"true\", \"split_pdf_concurrency_level\": 15}"

After the command successfully runs, see the results in the specified output path on your local machine.

​
Unstructured Ingest Python library

To work with the Unstructured Serverless API by using the Unstructured Python library, you will need to:

  • Install Python, and then install the CLI package:

    pip install unstructured-ingest

  • Set the following environment variables:

    • Set UNSTRUCTURED_API_KEY to your API key.
    • Set UNSTRUCTURED_API_URL to your API URL.

    Get your API key and API URL.

  • Have some compatible files on your local machine to be processed. See the list of supported file types. If you do not have any files available, you can download some from the example-docs folder in the Unstructured repo on GitHub.

Now, use the CLI to call the API, replacing:

  • <path/to/input> with the source (input) path to the directory on your local machine that contains the compatible files for Unstructured to process on its hosted compute resources.
  • <path/to/output> with the destination (output) path to the directory on your local machine that will contain the processed data that Unstructured returns from its hosted compute resources.
Python Ingest v2
import os

from unstructured_ingest.v2.pipeline.pipeline import Pipeline
from unstructured_ingest.v2.interfaces import ProcessorConfig
from unstructured_ingest.v2.processes.connectors.local import (
    LocalIndexerConfig,
    LocalDownloaderConfig,
    LocalConnectionConfig,
    LocalUploaderConfig
)
from unstructured_ingest.v2.processes.partitioner import PartitionerConfig

if __name__ == "__main__":
    Pipeline.from_configs(
        context=ProcessorConfig(),
        indexer_config=LocalIndexerConfig(input_path=os.getenv("LOCAL_FILE_INPUT_DIR")),
        downloader_config=LocalDownloaderConfig(),
        source_connection_config=LocalConnectionConfig(),
        partitioner_config=PartitionerConfig(
            partition_by_api=True,
            api_key=os.getenv("UNSTRUCTURED_API_KEY"),
            partition_endpoint=os.getenv("UNSTRUCTURED_API_URL"),
            strategy="hi_res",
            additional_partition_args={
                "split_pdf_page": True,
                "split_pdf_allow_failed": True,
                "split_pdf_concurrency_level": 15
            }
        ),
        uploader_config=LocalUploaderConfig(output_dir=os.getenv("LOCAL_FILE_OUTPUT_DIR"))
    ).run()

After the command successfully runs, see the results in the specified output path on your local machine.

​
Telemetry

We’ve partnered with Scarf to collect anonymized user statistics to understand which features our community is using and how to prioritize product decision-making in the future.

To learn more about how we collect and use this data, please read our Privacy Policy.

To opt out of this data collection, you can set the environment variable SCARF_NO_ANALYTICS=true before running any commands that call Unstructured Serverless API services.

Was this page helpful?

Suggest edits
Supported file typesFree Unstructured API