--- title: "Contentstack Delivery Python SDK" description: "Documentation for Python Delivery SDK" url: "https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/python/reference" product: "Contentstack" doc_type: "guide" audience: - developers - admins version: "current" last_updated: "2025-09-15" --- # Contentstack Delivery Python SDK ## Contentstack - Python Delivery SDK ## Python Delivery SDK for Contentstack Contentstack is a headless CMS with an API-first approach. It is a CMS that developers can use to build powerful cross-platform applications in their favorite languages. Build your application front end, and Contentstack will take care of the rest. [Read More](https://www.contentstack.com/docs/developers/java/). Contentstack provides Python Delivery SDK to build applications on top of Python. Given below is the detailed guide and helpful resources to get started with our Python Delivery SDK. ## Prerequisite This guide will help you get started with Contentstack [Python SDK](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/python/about-python-sdk/) to build apps powered by Contentstack. * [Contentstack account](https://app.contentstack.com/#!/login) * [Python 3](https://www.python.org/downloads/) ## SDK Installation and Setup To use the Contentstack Python SDK with your existing project, perform the following steps: 1. Open the terminal, create a project, and move inside it as follows: mkdir contentstack-example cd contentstack-example 2. Create a virtual environment: python3 -m venv venv 3. Activate the virtual environment: source venv/bin/activate 4. Install pip Contentstack as follows: pip install contentstack You can download the latest dependency version [here](https://pypi.org/project/Contentstack/) ## Quickstart in 5 mins ## Initializing your SDK Contentstack offers seven [regions](/docs/developers/contentstack-regions/about-regions) AWS North America (AWS NA), AWS Europe (AWS EU), AWS Australia (AWS AU), Azure North America (AZURE NA), Azure Europe (AZURE EU), GCP North America (GCP NA), and GCP Europe (GCP EU) as data centers to store customers' account details and data. These regions are independent of each other and therefore have a dedicated set of instructions to use SDKs offered by Contentstack. To use SDKs for the Europe, Azure NA, or Azure EU region, you will have to make certain changes in the configuration of the SDK, as detailed below, and the rest of the instructions remain the same. To initialize the SDK, the **stack’s api\_key delivery token** and the name of the **environment** where you will publish the content, as shown in the snippet below: import contentstack stack = contentstack.Stack(api\_key='api\_key', delivery\_token='delivery\_token', environment='environment') **Note**: By default, the SDK uses the North American region. Configuration changes are not required for North American region users. By default, the SDK uses the North American region. Configuration changes are not required for North American region users. Refer the below code if you want to use the Europe, Azure North America, Azure Europe, GCP North America, or GCP Europe region. import contentstack stack = contentstack.Stack("api\_key", "delivery\_token", "environment", region = "ContentstackRegion.AZURE\_EU") Once you have initialized the SDK, you can query entries to fetch the required content. For Setting the branch for Europe, Azure North America, Azure Europe, GCP North America, or GCP Europe, refer the code below **For Setting Branch:** If you want to initialize SDK in a particular branch use the code given below: import contentstack stack = contentstack.Stack(api\_key='api\_key', delivery\_token='delivery\_token',environment= 'environment', branch='branch') ## Basic Queries Contentstack SDKs let you interact with the [Content Delivery APIs](https://www.contentstack.com/docs/developers/apis/content-delivery-api) and retrieve content from Contentstack. They are read-only in nature. The SDKs fetch and deliver content from the nearest server via Fastly, our powerful and robust CDN. **Get a Single Entry** To retrieve a single [entry](https://www.contentstack.com/docs/content-managers/author-content/about-entries) from a [content type](https://www.contentstack.com/docs/developers/create-content-types/about-content-types), use the code snippet given below: import contentstack stack = contentstack.Stack(api\_key='api\_key', delivery\_token='delivery\_token', environment='environment') contentType = stack.content\_type("content\_type\_uid") entry = content\_type.entry("entry\_uid") response = entry.fetch() **Get Multiple Entries** To retrieve multiple entries of a particular content type, use the code snippet given below: import contentstack stack = contentstack.Stack(api\_key='api\_key', delivery\_token='delivery\_token', environment='environment') query = stack.content\_type("content\_type\_uid").query() response = query.find() **Note:** By default, the limit for response details per request is 100, with the maximum limit set at 250. ## Pagination In a single instance, the [Get Multiple Entries](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/python/get-started-with-python-sdk/#get-multiple-entries) query will **retrieve only the first 100 items** of the specified content type. You can paginate and retrieve the rest of the items in batches using the **skip** and **limit** parameters in subsequent requests. stack = contentstack.Stack(api\_key='api\_key', delivery\_token='delivery\_token', environment='environment') query = stack.content\_type('content\_type\_uid').query() response = query.locale('locale').limit(20).skip(20).find() ## Stack Retrieves stack ## live_preview_query live\_preview\_query accepts key-value pair objects to the query ## image_transform Image Delivery API covers the parameters that you can add to the URL to retrieve, manipulate (or convert) image files and display it to your web or mobile properties. ## sync_token You can use the sync token (that you receive after the initial sync)to get the updated content next time. The sync token fetchesonly the content that was addedafter your last sync and the details of the content that was deleted or updated. ## pagination If the result of the initial sync (or subsequent sync)contains more than 100 records, the response would bepaginated. It provides a pagination token in the response.However, you do not have to use the pagination tokenmanually to get the next batch. ## asset_query initial sync of the stack ## asset_query assets of the stack ## asset asset of the stack ## get_live_preview live\_preview for the stack ## get_headers headers for the stack ## get_branch branch for the stack ## get_environment environment for the stack ## get_delivery_token Delivery Token for the stack ## get_api_key api\_key for the stack ## early_access Array of header strings for early access features. Optional array of header strings for early access features. DB region for your stack. You can choose from seven regions namely, AWS NA, AWS EU, AWS AU, Azure NA, Azure EU, GCP NA, and GCP EU ## Asset Retrieves a single asset, specify its UID. Readonly property to check value of asset’s uid ## fetch This call fetches the latest version of a specific asset of a particular stack ## include_fallback Retrieve the published content of the fallback locale if an entry is not localized in specified locale ## include_dimension Include the dimensions (height and width) of the image in the response. Supported image types: JPG, GIF, PNG, WebP, BMP, TIFF, SVG, and PSD ## include_metadata Includes asset metadata along with response body. ## relative_urls Include the relative URLs of the assets in the response ## environment Provide the name of the environment if you wish to retrieve the assets published in a particular environment ## params params is used to pass additional parameters to the asset query ## remove_environment Removes environment from the request params ## AssetQuery Retrieves Assets Readonly property to get data of entry. ## find This call fetches the list of all the assets of a particular stack. It also returns the content of each asset in dict format. ## locale Enter locale code. e.g., en-us ## include_fallback Retrieve the published content of the fallback locale if an entry is not localized in specified locale ## include_metadata Includes AssetQuery metadata along with response body. ## relative_url include the relative URLs of the assets in the response ## include_branch Includes branch in the response ## version Specify the version number of the asset that you wish to retrieve. If the version is not specified, the details of the latest version will be retrieved. To retrieve a specific version, keep the environment parameter blank ## environment Provide the name of the environment if you wish to retrieve the assets published in a particular environment ## ContentType ContentType provides Entry and Query instance. ## query We can query on entry of specified ContentType ## fetch This method is useful to fetch ContentType of the stack ## find This method is useful to fetch ContentType of the of the stack. ## entry An entry is the actual piece of content created using one of the defined content types ## Entry Retrieves assets Read-only property to get the data of the entry. ## fetch Fetches the latest version of the entries from stack ## include_embedded_items include\_embedded\_items instance of Entry include\_embedded\_objects (Entries and Assets) along with entry/entries details ## include_branch Retrieve the published pranch in the entry response ## include_fallback Retrieve the published content of the fallback locale if an entry is not localized in specified locale ## include_metadata Includes entry metadata along with response body. ## param This method is useful to add additional Query parameters to the entry ## version When no version is specified, it returns the latest version, To retrieve a specific version, specify the version number under this parameter. In such a case, DO NOT specify any environment ## environment Enter the name of the environment of which the entries needs to be included ## Entry Variants Entry Variants let you create different versions of content for specific audiences, languages, or marketing experiments. Each variant is grouped under a Base Entry—the original content item. Entry Variants are the tailored versions, and all variants are organized into a Variant Group. This setup makes it easier to manage personalized content, maintain consistency, and apply updates across all versions efficiently. ## Get All Entry Variants The Get all entry variants request retrieves all entry variants of the specified entry. To fetch specific variants, pass one or more variant UIDs in the x-cs-variant-uid header. This returns only the variants applied to the specified entries. **Note:** You can add up to three variant UIDs in the x-cs-variant-uid header, separated by commas. The first UID in the list has the highest priority and its content will be used first. \>For example, if you enter Red, Green, and Blue in that order, Red will be given priority. Example: x-cs-variant-uid: cs6c42daef493fb432, cs7697ce80c9bbcc3e, cs8697ce80c9bbcc4f You can add other Queries to extend the functionality of this API call. **Note:** * The API timeout for entry variants is capped at 10 seconds. * The maximum response document size for all entry variants is 10 MB ## Get a Single Entry Variants The Get a single entry variant request retrieves a single variant entry of a given base entry. To fetch variants applied to your entries, pass the the variant UID(s) in the x-cs-variant-uid header. **Note:** You can add up to three variant UIDs in the x-cs-variant-uid header, separated by commas. The first UID in the list has the highest priority and its content will be used first. For example, if you enter Red, Green, and Blue in that order, Red will be given priority.Example: x-cs-variant-uid: cs6c42daef493fb432, cs7697ce80c9bbcc3e, cs8697ce80c9bbcc4f You can add other Queries to extend the functionality of this API call. **Note:** * The API timeout for entry variants is capped at 10 seconds. * The maximum response document size for all entry variants is 10 MB ## Global Fields A [Global field](/docs/developers/global-field/about-global-field/) is a reusable field or group of fields that you define once and reuse across any content type in your stack. This helps you avoid recreating the same set of fields multiple times, saving time and effort. ## fetch The fetch method retrieves data for the specified global field. ## find The find method retrieves all global fields in the stack. ## Query Retrieves assets ## query Adds key value pairs to the to the query parameters ## addParams Adds Query Parameters to the to the request ## param Adds Query Parameters to the to the request ## order_by_descending you can sort them in the descending order with respect to the value of a specific field in the response body ## order_by_ascending you can sort them in the ascending order with respect to the value of a specific field in the response body. ## limit A limit on the number of objects to return./p> ## skip The number of objects to skip before returning any. skip\_count No of objects to skip from returned objects ## include_count Retrieve count and data of objects in result ## where Get entries containing the field values matching the condition in the query ## add_param This method adds key and value to the Query ## include_reference_content_type_uid This method also includes the content type UIDs of the referenced entries returned in the response ## include_content_type This method also includes the ContentType in the entry ## include_reference When you fetch an entry of a content type that has a reference field, by default, the content of the referred entry is not fetched. It only fetches the UID of the referred entry, along with the content of the specified entry ## excepts Specifies list of field\_uid that would be excluded from the response. It refers to the top-level fields of the schema ## only Specifies an array of only keys in BASE object that would be included in the response. It refers to the top-level fields of the schema ## find_one It fetches single query response ## locale Language code of which the entries need to be included. Only the entries published in this locale will be displayed ## find It fetches the query response ## include_embedded_items Retrieve the published pranch in the response ## include_branch Retrieve the published pranch in the response ## include_fallback Retrieve the published content of the fallback locale if an entry is not localized in specified locale ## include_metadata Includes Query metadata along with response body. ## where_not_in Get entries having values based on referenced fields. This query works the opposite of $in\_query and retrieves all entries that does not satisfy query conditions made on referenced fields. ## where_in Get entries having values based on referenced fields. This query retrieves all entries that satisfy the query conditions made on referenced fields ## search This method provides only the entries matching the specified value. ## tags Include tags with which to search entries that accept variable-length argument lists ## query_operator query\_operator Get entries that satisfy all the conditions provided in the '$and' query.