---
title: Python SDK Quickstart | Tabstack
description: Get up and running with the Tabstack Python SDK in minutes. Installation, authentication, and your first API call.
---

Get up and running with the Tabstack Python SDK in minutes. This guide will walk you through installation, authentication, and your first API call.

## Prerequisites

- **Python** >= 3.9
- **Package manager**: pip, uv, poetry, or pipenv
- **Tabstack API key** from [console.tabstack.ai](https://console.tabstack.ai)

## Installation

Install the SDK using your preferred package manager:

- [uv](#tab-panel-50)
- [pip](#tab-panel-51)
- [poetry](#tab-panel-52)
- [pipenv](#tab-panel-53)

Terminal window

```
uv pip install tabstack
```

Or add to your project:

Terminal window

```
uv add tabstack
```

Terminal window

```
pip install tabstack
```

Terminal window

```
poetry add tabstack
```

Terminal window

```
pipenv install tabstack
```

The current SDK version is **2.0.0**.

## Get Your API Key

Before you can start using the SDK, you’ll need to create an API key:

1. Visit the [Tabstack Console](https://console.tabstack.ai/)
2. Sign in to your account (or create one if you haven’t already)
3. Navigate to the API Keys section and click “Manage API Keys”
4. Click “Create New API Key”
5. Give your key a descriptive name (e.g., “Development”, “Production”)
6. Copy the generated API key and store it securely

**Important**: Your API key will only be shown once. Make sure to copy and store it in a secure location.

## Set Up Environment Variable

For security and convenience, store your API key as an environment variable:

**macOS/Linux:**

Terminal window

```
# Add to your shell profile (~/.bashrc, ~/.zshrc, or ~/.bash_profile)
export TABSTACK_API_KEY="your_api_key_here"


# Or set it temporarily for the current session
export TABSTACK_API_KEY="your_api_key_here"


# Reload your shell or run:
source ~/.bashrc  # or ~/.zshrc
```

**Windows (Command Prompt):**

Terminal window

```
# Set temporarily for current session
set TABSTACK_API_KEY=your_api_key_here


# Set permanently (requires restart)
setx TABSTACK_API_KEY "your_api_key_here"
```

**Windows (PowerShell):**

Terminal window

```
# Set temporarily for current session
$env:TABSTACK_API_KEY = "your_api_key_here"


# Set permanently for current user
[Environment]::SetEnvironmentVariable("TABSTACK_API_KEY", "your_api_key_here", "User")
```

## Your First API Call

The Python SDK provides both synchronous and asynchronous clients. Use context managers for automatic resource cleanup.

### Sync Example (Recommended for Simple Scripts)

```
import os
from tabstack import Tabstack


# Initialize the sync client with context manager
with Tabstack(api_key=os.getenv('TABSTACK_API_KEY')) as client:
    try:
        # Extract markdown from a URL
        result = client.extract.markdown(url='https://example.com')
        print(result.content)
    except Exception as error:
        print(f'Error: {error}')
```

### Async Example

If you need async support, use `AsyncTabstack`:

```
import asyncio
import os
from tabstack import AsyncTabstack


async def main():
    # Initialize the async client with async context manager
    async with AsyncTabstack(api_key=os.getenv('TABSTACK_API_KEY')) as client:
        try:
            # Extract markdown from a URL
            result = await client.extract.markdown(url='https://example.com')
            print(result.content)
        except Exception as error:
            print(f'Error: {error}')


# Run the async function
asyncio.run(main())
```

**Response:**

```
---
title: Example Domain
description: Example Domain
url: https://example.com
type: website
---


# Example Domain


This domain is for use in illustrative examples in documents. You may use this
domain in literature without prior coordination or asking for permission.


[More information...](https://www.iana.org/domains/example)
```

## Core Features

The SDK provides three main operators for working with web content:

### Extract

Convert web pages to structured data:

- **Markdown**: Convert HTML to clean Markdown format
- **JSON**: Extract structured data matching your schema

### Generate

Transform web content using AI:

- Summarize and analyze content
- Categorize and tag data
- Perform sentiment analysis
- Extract key insights with custom instructions

[Learn more about Generate features →](./generate)

### Automate

Execute browser automation tasks with natural language:

- Web scraping with real-time updates
- Form filling and submission
- Multi-step workflows
- Streaming progress events

[Learn more about Automate features →](./automate)

## Quick Example: Extract Structured Data

Here’s a more advanced example that extracts structured data from a web page:

```
import os
from tabstack import Tabstack


with Tabstack(api_key=os.getenv('TABSTACK_API_KEY')) as client:
    # Define the data structure you want
    schema = {
        "type": "object",
        "properties": {
            "stories": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "title": {"type": "string"},
                        "points": {"type": "number"},
                        "author": {"type": "string"}
                    },
                    "required": ["title", "points", "author"]
                }
            }
        },
        "required": ["stories"]
    }


    try:
        # Extract data matching the schema
        result = client.extract.json(
            url='https://news.ycombinator.com',
            json_schema=schema
        )


        print(f"Found {len(result['stories'])} stories:")
        for story in result['stories'][:3]:  # Show first 3
            print(f"- {story['title']} ({story['points']} points) by {story['author']}")


    except Exception as error:
        print(f'Error: {error}')
```

## Client Configuration

The SDK provides several configuration options:

```
import httpx
from tabstack import Tabstack


client = Tabstack(
    api_key="your-api-key",                    # Required (or TABSTACK_API_KEY env var)
    base_url="https://api.tabstack.ai/v1",     # Optional, defaults to this
    timeout=60.0,                              # Request timeout in seconds (default: 60)
    max_retries=2,                             # Max retry attempts (default: 2)
    default_headers={"X-Custom": "header"},    # Optional custom headers
)
```

### Environment Variables

| Variable            | Description                                |
| ------------------- | ------------------------------------------ |
| `TABSTACK_API_KEY`  | API key for authentication                 |
| `TABSTACK_BASE_URL` | Override the default API base URL          |
| `TABSTACK_LOG`      | Set to `info` or `debug` to enable logging |

### Timeout Configuration

For more granular control over timeouts:

```
import httpx
from tabstack import Tabstack


client = Tabstack(
    timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0)
)
```

## Concurrent Requests (Async)

Use `asyncio.gather()` for concurrent requests with the async client:

```
import asyncio
import os
from tabstack import AsyncTabstack


async def fetch_multiple():
    async with AsyncTabstack(api_key=os.getenv('TABSTACK_API_KEY')) as client:
        # Run multiple requests concurrently
        results = await asyncio.gather(
            client.extract.markdown(url='https://example.com/1'),
            client.extract.markdown(url='https://example.com/2'),
            client.extract.markdown(url='https://example.com/3'),
            return_exceptions=True  # Don't fail all if one fails
        )


        for i, result in enumerate(results):
            if isinstance(result, Exception):
                print(f"Request {i} failed: {result}")
            else:
                print(f"Request {i}: {len(result.content)} characters")


asyncio.run(fetch_multiple())
```

## Per-Request Options

Override client defaults for individual requests:

```
from tabstack import Tabstack


with Tabstack() as client:
    # Override timeout and retries for this specific request
    result = client.with_options(
        timeout=120.0,
        max_retries=5
    ).extract.json(
        url='https://example.com',
        json_schema={"type": "object", "properties": {"title": {"type": "string"}}}
    )
```

## Best Practices

### Using Context Managers

Always use context managers to ensure proper cleanup:

```
# Sync - Good: Automatic cleanup
with Tabstack(api_key=api_key) as client:
    result = client.extract.markdown(url=url)


# Sync - Not recommended: Manual cleanup required
client = Tabstack(api_key=api_key)
try:
    result = client.extract.markdown(url=url)
finally:
    client.close()


# Async - Good: Automatic cleanup
async with AsyncTabstack(api_key=api_key) as client:
    result = await client.extract.markdown(url=url)
```

### Error Handling

Always wrap API calls in try-except blocks:

```
from tabstack import Tabstack, TabstackError


with Tabstack(api_key=api_key) as client:
    try:
        result = client.extract.markdown(url='https://example.com')
        return result
    except TabstackError as error:
        print(f"API error: {error}")
        return None
```

## Next Steps

Now that you’re up and running:

1. **[Generate Features](./generate)**: Discover AI-powered content transformation and analysis
2. **[Automate Features](./automate)**: Execute complex browser automation tasks with streaming updates
3. **[Error Handling](./error-handling)**: Build robust applications with proper error handling

## Need Help?

- **API Reference**: [REST API Documentation](/api/index.md)
- **PyPI**: [Python Package Index](https://pypi.org/project/tabstack/)
- **GitHub**: [Python SDK Repository](https://github.com/Mozilla-Ocho/tabstack-python)
- **Documentation**: [docs.tabstack.ai](https://docs.tabstack.ai)
- **Support**: <tabstack-support@mozilla.com>