### Install ExportComments Python Package

Source: https://github.com/exportcomments/exportcomments-python/blob/main/README.md

Install the package using pip. Alternatively, clone the repository and install from source.

```bash
pip install exportcomments
```

```bash
git clone https://github.com/exportcomments/exportcomments-python.git
cd exportcomments-python
pip install -r requirements.txt
python setup.py install
```

--------------------------------

### Complete Export Process Example

Source: https://github.com/exportcomments/exportcomments-python/blob/main/README.md

A comprehensive example demonstrating client initialization, connectivity check, job creation, status polling, and file download.

```python
from exportcomments import ExportComments
from exportcomments.exceptions import ExportCommentsException
import time
import sys

ex = ExportComments('<YOUR API TOKEN HERE>')

# Verify connectivity
print(ex.ping())

# Create export
try:
    response = ex.jobs.create(
        url='https://www.instagram.com/p/1234567',
        options={'replies': True, 'limit': 100}
    )
except ExportCommentsException as e:
    print(e)
    sys.exit()

guid = response.body['guid']

# Poll until done
while True:
    response = ex.jobs.check(guid=guid)
    status = response.body['status']

    if status == 'done':
        break
    elif status == 'error':
        print("Error:", response.body.get('error'))
        sys.exit()

    time.sleep(5)

# Download the file
file_path = ex.jobs.download(guid=guid)
print(f"Downloaded: {file_path}")

# Or get raw JSON data
data = ex.jobs.download_json(guid=guid)
print(f"Got {len(data)} comments")
```

--------------------------------

### Create an Export Job

Source: https://github.com/exportcomments/exportcomments-python/blob/main/README.md

Start an export job by providing a URL and optional parameters like replies and limit. The queue supports 5 concurrent requests.

```python
response = ex.jobs.create(
    url='https://www.instagram.com/p/1234567',
    options={'replies': True, 'limit': 100}
)
guid = response.body['guid']
```

--------------------------------

### List Jobs and Process Results

Source: https://context7.com/exportcomments/exportcomments-python/llms.txt

Fetches the first page of jobs with a limit of 10. Processes the response body, which is a list of job dictionaries, printing their GUID, status, and URL.

```python
response = ex.jobs.list(page=1, limit=10)
jobs = response.body  # list of job dicts

for job in jobs:
    print(job['guid'], job['status'], job.get('url'))
```

--------------------------------

### ex.jobs.check(guid)

Source: https://context7.com/exportcomments/exportcomments-python/llms.txt

Fetches the current state of a job by its GUID. The status cycles through `'queueing'`, `'progress'`, `'done'`, or `'error'`. For completed jobs, it also provides download URLs.

```APIDOC
## ex.jobs.check(guid) — Check Job Status

Fetches the current state of a job by its GUID. The `status` field in `response.body` cycles through `'queueing'` → `'progress'` → `'done'` (or `'error'`). A completed job body also contains `download_url`, `file_name`, and `json_url`.

```python
import time
from exportcomments import ExportComments
from exportcomments.exceptions import ExportCommentsException

ex = ExportComments('<YOUR_API_TOKEN>')
guid = 'previously-returned-guid'

while True:
    response = ex.jobs.check(guid=guid)
    job = response.body

    print(f"Status: {job['status']}")  # queueing / progress / done / error

    if job['status'] == 'done':
        print("Download URL:", job.get('download_url'))
        print("JSON URL:", job.get('json_url'))
        break
    elif job['status'] == 'error':
        print("Export failed:", job.get('error'))
        break

    time.sleep(5)  # poll every 5 seconds
```
```

--------------------------------

### Download Raw JSON Data

Source: https://context7.com/exportcomments/exportcomments-python/llms.txt

Fetches the completed export as a parsed Python list of dictionaries. Each dictionary represents a comment or review. Requires a valid job GUID.

```python
from exportcomments import ExportComments
from exportcomments.exceptions import ExportCommentsException

ex = ExportComments('<YOUR_API_TOKEN>')
guid = 'previously-returned-guid'

try:
    comments = ex.jobs.download_json(guid=guid)
    print(f"Total comments: {len(comments)}")

    for comment in comments[:5]:
        print(f"[{comment.get('date')}] {comment.get('author_name')}: {comment.get('message')}")

except ValueError as e:
    print("Job not ready (no JSON URL):", e)
except ExportCommentsException as e:
    print("API error:", e)

# Expected output:
# Total comments: 342
# [2024-01-15] john_doe: Great post!
# [2024-01-15] jane_smith: Love this content
```

--------------------------------

### ExportComments.ping()

Source: https://context7.com/exportcomments/exportcomments-python/llms.txt

Checks API connectivity by sending a lightweight GET request. Returns a dict `{'message': 'pong'}` on success.

```APIDOC
## ExportComments.ping() — Check API Connectivity

Sends a lightweight GET request to verify that the API is reachable and the token is valid. Returns a dict `{'message': 'pong'}` on success.

```python
from exportcomments import ExportComments
from exportcomments.exceptions import AuthenticationError

ex = ExportComments('<YOUR_API_TOKEN>')

try:
    result = ex.ping()
    print(result)  # {'message': 'pong'}
except AuthenticationError as e:
    print("Invalid token:", e)
```
```

--------------------------------

### Download Export File (Excel/XLSX/CSV)

Source: https://context7.com/exportcomments/exportcomments-python/llms.txt

Downloads a completed export as a binary file. It can save to the current directory with an auto-generated name or to a specified output path. Requires a valid job GUID.

```python
import os
from exportcomments import ExportComments
from exportcomments.exceptions import ExportCommentsException

ex = ExportComments('<YOUR_API_TOKEN>')
guid = 'previously-returned-guid'

try:
    # Auto-named file saved in current directory
    file_path = ex.jobs.download(guid=guid)
    print(f"Saved to: {file_path}")  # e.g., /home/user/export-<guid>.xlsx

    # Or specify a custom output path
    file_path = ex.jobs.download(guid=guid, output_path='/tmp/my_export.xlsx')
    print(f"File size: {os.path.getsize(file_path)} bytes")

except ValueError as e:
    print("Job not ready for download:", e)
except ExportCommentsException as e:
    print("API error:", e)
```

--------------------------------

### Download Export File

Source: https://github.com/exportcomments/exportcomments-python/blob/main/README.md

Download the completed export file (Excel/CSV) for a given job GUID. You can specify a custom output path.

```python
# Downloads and saves the file, returns the file path
file_path = ex.jobs.download(guid=guid)
print(f"Saved to: {file_path}")

# Or specify a custom output path
file_path = ex.jobs.download(guid=guid, output_path='my_export.xlsx')
```

--------------------------------

### Download Export File

Source: https://github.com/exportcomments/exportcomments-python/blob/main/README.md

Downloads the completed export file (Excel/CSV) for a given job GUID. Allows specifying a custom output path.

```APIDOC
## Download Export File

### Description
Downloads the Excel/CSV file for a completed job.

### Method
`jobs.download(guid, output_path=None)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **guid** (string) - Required - The unique identifier of the job.
- **output_path** (string) - Optional - The custom path to save the file. If not provided, a default path is used.

### Request Example
```python
# Downloads and saves the file, returns the file path
file_path = ex.jobs.download(guid=guid)
print(f"Saved to: {file_path}")

# Or specify a custom output path
file_path = ex.jobs.download(guid=guid, output_path='my_export.xlsx')
```

### Response
#### Success Response (200)
- **file_path** (string) - The path where the file was saved.
```

--------------------------------

### Check Job Status

Source: https://github.com/exportcomments/exportcomments-python/blob/main/README.md

Retrieves the current status of an export job using its GUID.

```APIDOC
## Check Job Status

### Description
Retrieves the current status of an export job.

### Method
`jobs.check(guid)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **guid** (string) - Required - The unique identifier of the job.

### Request Example
```python
response = ex.jobs.check(guid=guid)
status = response.body['status']
```

### Response
#### Success Response (200)
- **status** (string) - The status of the job ('queueing', 'progress', 'done', or 'error').
- **error** (string, optional) - Error message if the status is 'error'.

#### Response Example
```json
{
  "status": "done"
}
```
```

--------------------------------

### Check Job Status

Source: https://github.com/exportcomments/exportcomments-python/blob/main/README.md

Retrieve the current status of an export job using its GUID. Possible statuses include 'queueing', 'progress', 'done', or 'error'.

```python
response = ex.jobs.check(guid=guid)
status = response.body['status']  # 'queueing', 'progress', 'done', or 'error'
```

--------------------------------

### Check Job Status with jobs.check()

Source: https://context7.com/exportcomments/exportcomments-python/llms.txt

Poll the status of an export job using its GUID. The job status cycles through 'queueing', 'progress', and 'done' or 'error'. For completed jobs, it provides download and JSON URLs.

```python
import time
from exportcomments import ExportComments
from exportcomments.exceptions import ExportCommentsException

ex = ExportComments('<YOUR_API_TOKEN>')
guid = 'previously-returned-guid'

while True:
    response = ex.jobs.check(guid=guid)
    job = response.body

    print(f"Status: {job['status']}")  # queueing / progress / done / error

    if job['status'] == 'done':
        print("Download URL:", job.get('download_url'))
        print("JSON URL:", job.get('json_url'))
        break
    elif job['status'] == 'error':
        print("Export failed:", job.get('error'))
        break

    time.sleep(5)  # poll every 5 seconds
```

--------------------------------

### ex.jobs.create(url, options)

Source: https://context7.com/exportcomments/exportcomments-python/llms.txt

Submits a URL to be scraped. The `options` dict supports various parameters to customize the export. Returns an `ExportCommentsResponse` object.

```APIDOC
## ex.jobs.create(url, options) — Create an Export Job

Submits a URL to be scraped. The queue allows up to 5 concurrent jobs. The `options` dict supports `replies` (bool), `limit` (int), `minTimestamp`/`maxTimestamp` (Unix epoch ints), `vpn` (country string), and `cookies` (dict). Returns an `ExportCommentsResponse`; `response.body['guid']` is the job identifier needed for all subsequent calls.

```python
from exportcomments import ExportComments
from exportcomments.exceptions import (
    ExportCommentsException,
    RequestParamsError,
    ConcurrencyRateLimitError,
    PlanRateLimitError,
)

ex = ExportComments('<YOUR_API_TOKEN>')

try:
    response = ex.jobs.create(
        url='https://www.instagram.com/p/ABC123/',
        options={
            'replies': True,       # include comment replies
            'limit': 500,          # max comments to export
            'minTimestamp': 1622505600,  # Unix epoch: 2021-06-01
            'maxTimestamp': 1625097600,  # Unix epoch: 2021-07-01
            'vpn': 'Norway',       # route request through VPN exit node
            'cookies': {
                'sessionid': 'abc123xyz'  # pass authenticated session
            }
        }
    )
    guid = response.body['guid']
    print("Job created:", guid)

except RequestParamsError as e:
    print("Bad parameters:", e)
except PlanRateLimitError as e:
    print(f"Rate limited, retry in {e.seconds_to_wait}s")
except ConcurrencyRateLimitError as e:
    print("Too many concurrent requests:", e)
except ExportCommentsException as e:
    print("API error:", e)
```
```

--------------------------------

### Create an Export Job with jobs.create()

Source: https://context7.com/exportcomments/exportcomments-python/llms.txt

Submit a URL to create an export job. The options dictionary allows customization of replies, limit, timestamps, VPN usage, and cookies for authenticated sessions. Handles various rate limit and request parameter errors.

```python
from exportcomments import ExportComments
from exportcomments.exceptions import (
    ExportCommentsException,
    RequestParamsError,
    ConcurrencyRateLimitError,
    PlanRateLimitError,
)

ex = ExportComments('<YOUR_API_TOKEN>')

try:
    response = ex.jobs.create(
        url='https://www.instagram.com/p/ABC123/',
        options={
            'replies': True,       # include comment replies
            'limit': 500,          # max comments to export
            'minTimestamp': 1622505600,  # Unix epoch: 2021-06-01
            'maxTimestamp': 1625097600,  # Unix epoch: 2021-07-01
            'vpn': 'Norway',       # route request through VPN exit node
            'cookies': {
                'sessionid': 'abc123xyz'  # pass authenticated session
            }
        }
    )
    guid = response.body['guid']
    print("Job created:", guid)

except RequestParamsError as e:
    print("Bad parameters:", e)
except PlanRateLimitError as e:
    print(f"Rate limited, retry in {e.seconds_to_wait}s")
except ConcurrencyRateLimitError as e:
    print("Too many concurrent requests:", e)
except ExportCommentsException as e:
    print("API error:", e)
```

--------------------------------

### Initialize ExportComments Client

Source: https://github.com/exportcomments/exportcomments-python/blob/main/README.md

Initialize the client with your API token obtained from app.exportcomments.com.

```python
from exportcomments import ExportComments

ex = ExportComments('<YOUR API TOKEN HERE>')
```

--------------------------------

### Configure Job Options

Source: https://github.com/exportcomments/exportcomments-python/blob/main/README.md

Customize export jobs with various options, including replies, limits, timestamps, VPN, and cookies.

```python
response = ex.jobs.create(
    url='https://www.instagram.com/p/1234567',
    options={
        'replies': True,
        'limit': 500,
        'minTimestamp': 1622505600,
        'maxTimestamp': 1625097600,
        'vpn': 'Norway',
        'cookies': {
            'sessionid': 'your_session_id'
        }
    }
)
```

--------------------------------

### ex.jobs.list(page, limit)

Source: https://context7.com/exportcomments/exportcomments-python/llms.txt

Returns a paginated list of all jobs associated with your API token. Both `page` and `limit` are optional integers.

```APIDOC
## ex.jobs.list(page, limit) — List All Jobs

Returns a paginated list of all jobs associated with your API token. Both `page` and `limit` are optional integers.

```python
from exportcomments import ExportComments

ex = ExportComments('<YOUR_API_TOKEN>')

```
```

--------------------------------

### Use Backward Compatibility Alias

Source: https://github.com/exportcomments/exportcomments-python/blob/main/README.md

The `ex.exports` object is an alias for `ex.jobs` for backward compatibility.

```python
response = ex.exports.create(
    url='https://www.instagram.com/p/1234567',
    options={'replies': True}
)
```

--------------------------------

### Initialize ExportComments Client

Source: https://context7.com/exportcomments/exportcomments-python/llms.txt

Initialize the ExportComments client with your API token. An optional base URL can be provided to point to a custom API endpoint.

```python
from exportcomments import ExportComments

# Initialize with your API token from https://app.exportcomments.com/user/api
ex = ExportComments('<YOUR_API_TOKEN>')

# Optional: point at a custom base URL (defaults to https://exportcomments.com/api/v3)
ex_custom = ExportComments('<YOUR_API_TOKEN>', base_url='https://exportcomments.com/api/v3')
```

--------------------------------

### List All Jobs with jobs.list()

Source: https://context7.com/exportcomments/exportcomments-python/llms.txt

Retrieve a paginated list of all export jobs associated with your API token. The 'page' and 'limit' parameters are optional integers for controlling pagination.

```python
from exportcomments import ExportComments

ex = ExportComments('<YOUR_API_TOKEN>')

```

--------------------------------

### Complete End-to-End Export Workflow with Python SDK

Source: https://context7.com/exportcomments/exportcomments-python/llms.txt

This script demonstrates the full lifecycle of exporting comments: submitting a job, polling for completion, and downloading results as both an Excel file and a JSON structure. It includes essential error handling for authentication and rate limiting. Ensure you replace '<YOUR_API_TOKEN>' with your actual API token.

```python
import time
import sys
from exportcomments import ExportComments
from exportcomments.exceptions import (
    ExportCommentsException,
    PlanRateLimitError,
    AuthenticationError,
)

ex = ExportComments('<YOUR_API_TOKEN>')

# 1. Verify connectivity
pong = ex.ping()
print(pong)  # {'message': 'pong'}

# 2. Submit export job
try:
    response = ex.jobs.create(
        url='https://www.youtube.com/watch?v=dQw4w9WgXcQ',
        options={'replies': True, 'limit': 200}
    )
except AuthenticationError:
    print("Check your API token at https://app.exportcomments.com/user/api")
    sys.exit(1)
except ExportCommentsException as e:
    print("Failed to create job:", e)
    sys.exit(1)

guid = response.body['guid']
print(f"Job submitted: {guid}")

# 3. Poll for completion
while True:
    try:
        check = ex.jobs.check(guid=guid)
    except PlanRateLimitError as e:
        time.sleep(e.seconds_to_wait)
        continue

    status = check.body['status']
    print(f"Status: {status}")

    if status == 'done':
        break
    elif status == 'error':
        print("Export error:", check.body.get('error'))
        sys.exit(1)

    time.sleep(5)

# 4a. Download as Excel file
file_path = ex.jobs.download(guid=guid, output_path='youtube_comments.xlsx')
print(f"Excel saved: {file_path}")

# 4b. Or retrieve as structured JSON
comments = ex.jobs.download_json(guid=guid)
print(f"Total comments fetched: {len(comments)}")
for c in comments[:3]:
    print(f"  {c.get('author_name')}: {c.get('message')[:80]}")

```

--------------------------------

### Create Export Job

Source: https://github.com/exportcomments/exportcomments-python/blob/main/README.md

Initiates an export job for a given URL. The API queue has a limit of 5 concurrent requests.

```APIDOC
## Create Export Job

### Description
Starts an export by submitting a URL. The queue is limited to 5 concurrent requests.

### Method
`jobs.create(url, options=None)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **url** (string) - Required - The URL of the content to export comments from.
- **options** (dict) - Optional - Configuration options for the export.
  - **replies** (boolean) - Whether to include replies.
  - **limit** (integer) - The maximum number of comments to export.
  - **minTimestamp** (integer) - Minimum timestamp for comments.
  - **maxTimestamp** (integer) - Maximum timestamp for comments.
  - **vpn** (string) - VPN country to use for the request.
  - **cookies** (dict) - Dictionary of cookies to use for the request.

### Request Example
```python
response = ex.jobs.create(
    url='https://www.instagram.com/p/1234567',
    options={'replies': True, 'limit': 100}
)
guid = response.body['guid']
```

### Response
#### Success Response (200)
- **guid** (string) - The unique identifier for the created job.

#### Response Example
```json
{
  "guid": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}
```
```

--------------------------------

### Check API Connectivity

Source: https://github.com/exportcomments/exportcomments-python/blob/main/README.md

Use the ping method to verify API connectivity. Expects a {'message': 'pong'} response.

```python
result = ex.ping()
print(result)  # {'message': 'pong'}
```

--------------------------------

### Check API Connectivity with ping()

Source: https://context7.com/exportcomments/exportcomments-python/llms.txt

Use the ping() method to verify API reachability and token validity. It returns a dictionary with a 'pong' message on success and raises an AuthenticationError for invalid tokens.

```python
from exportcomments import ExportComments
from exportcomments.exceptions import AuthenticationError

ex = ExportComments('<YOUR_API_TOKEN>')

try:
    result = ex.ping()
    print(result)  # {'message': 'pong'}
except AuthenticationError as e:
    print("Invalid token:", e)
```

--------------------------------

### Backward Compatibility Alias

Source: https://github.com/exportcomments/exportcomments-python/blob/main/README.md

For backward compatibility, `ex.exports` can be used as an alias for `ex.jobs`.

```APIDOC
## Backward Compatibility Alias

### Description
For backward compatibility, `ex.exports` still works as an alias for `ex.jobs`.

### Request Example
```python
response = ex.exports.create(
    url='https://www.instagram.com/p/1234567',
    options={'replies': True}
)
```
```

--------------------------------

### ExportComments(token, base_url)

Source: https://context7.com/exportcomments/exportcomments-python/llms.txt

Initializes the ExportComments client. Accepts an API token and an optional base URL.

```APIDOC
## ExportComments(token, base_url) — Initialize the Client

The top-level client class. Accepts an API token (required) and an optional `base_url` override. Exposes `jobs` (and its alias `exports` for backward compatibility) as well as the `ping()` connectivity check.

```python
from exportcomments import ExportComments

# Initialize with your API token from https://app.exportcomments.com/user/api
ex = ExportComments('<YOUR_API_TOKEN>')

# Optional: point at a custom base URL (defaults to https://exportcomments.com/api/v3)
ex_custom = ExportComments('<YOUR_API_TOKEN>', base_url='https://exportcomments.com/api/v3')
```
```

--------------------------------

### Handle ExportComments SDK Exceptions

Source: https://context7.com/exportcomments/exportcomments-python/llms.txt

Demonstrates how to catch various exceptions from the ExportComments SDK, including authentication, rate limiting, and general API errors. Specific exceptions provide additional attributes like status codes or wait times.

```python
from exportcomments.exceptions import (
    ExportCommentsException,       # base class for all exceptions
    RequestParamsError,            # 422 – invalid request parameters
    AuthenticationError,           # 401 – bad or missing API token
    ForbiddenError,                # 403 – insufficient permissions
    ModelLimitError,               # 403 MODEL_LIMIT – plan job limit reached
    ResourceNotFound,              # 404 – job GUID not found
    PlanRateLimitError,            # 429 PLAN_RATE_LIMIT – per-minute limit
    ConcurrencyRateLimitError,     # 429 CONCURRENCY_RATE_LIMIT – per-second limit
    PlanQueryLimitError,           # 429 PLAN_QUERY_LIMIT – monthly query quota
    ModelStateError,               # 423 – job in invalid state for action
)

from exportcomments import ExportComments

ex = ExportComments('<YOUR_API_TOKEN>')

try:
    response = ex.jobs.create(url='https://www.instagram.com/p/ABC123/')

except AuthenticationError as e:
    print(f"Auth failed [{e.status_code}]: {e.detail}")

except PlanRateLimitError as e:
    import time
    print(f"Rate limited. Waiting {e.seconds_to_wait}s...")
    time.sleep(e.seconds_to_wait)

except ForbiddenError as e:
    print(f"Forbidden [{e.error_code}]: {e.detail}")

except ExportCommentsException as e:
    # Catch-all for any other SDK exception
    print("Unexpected error:", e)
```

--------------------------------

### Download Export File

Source: https://context7.com/exportcomments/exportcomments-python/llms.txt

Downloads the completed export as a binary Excel/XLSX file (or CSV, depending on plan). Internally calls `check()` to retrieve the `download_url`, then streams the file to disk. Returns the absolute path of the saved file.

```APIDOC
## `ex.jobs.download(guid, output_path)` — Download Export File

Downloads the completed export as a binary Excel/XLSX file (or CSV, depending on plan). Internally calls `check()` to retrieve the `download_url`, then streams the file to disk. Returns the absolute path of the saved file.

### Parameters
- **guid** (string) - Required - The unique identifier for the export job.
- **output_path** (string) - Optional - The custom path to save the downloaded file. If not provided, the file is saved in the current directory with an auto-generated name.

### Request Example
```python
import os
from exportcomments import ExportComments
from exportcomments.exceptions import ExportCommentsException

ex = ExportComments('<YOUR_API_TOKEN>')
guid = 'previously-returned-guid'

try:
    # Auto-named file saved in current directory
    file_path = ex.jobs.download(guid=guid)
    print(f"Saved to: {file_path}")  # e.g., /home/user/export-<guid>.xlsx

    # Or specify a custom output path
    file_path = ex.jobs.download(guid=guid, output_path='/tmp/my_export.xlsx')
    print(f"File size: {os.path.getsize(file_path)} bytes")

except ValueError as e:
    print("Job not ready for download:", e)
except ExportCommentsException as e:
    print("API error:", e)
```

### Response
- Returns the absolute path of the saved file.
```

--------------------------------

### Exception Hierarchy

Source: https://context7.com/exportcomments/exportcomments-python/llms.txt

All SDK exceptions extend `ExportCommentsException`. Response exceptions carry `status_code`, `detail`, `error_code`, and `response` attributes. `PlanRateLimitError` additionally exposes `seconds_to_wait`.

```APIDOC
## Exception Hierarchy

All SDK exceptions extend `ExportCommentsException`. Response exceptions carry `status_code`, `detail`, `error_code`, and `response` attributes. `PlanRateLimitError` additionally exposes `seconds_to_wait`.

### Base Exception
- `ExportCommentsException`: Base class for all SDK exceptions.

### Specific Exceptions
- `ValueError`: Raised when a job is not ready for download or has no JSON URL.
- `RequestParamsError` (422): Invalid request parameters.
- `AuthenticationError` (401): Bad or missing API token.
- `ForbiddenError` (403): Insufficient permissions.
- `ModelLimitError` (403 MODEL_LIMIT): Plan job limit reached.
- `ResourceNotFound` (404): Job GUID not found.
- `PlanRateLimitError` (429 PLAN_RATE_LIMIT): Per-minute rate limit exceeded. Exposes `seconds_to_wait`.
- `ConcurrencyRateLimitError` (429 CONCURRENCY_RATE_LIMIT): Per-second rate limit exceeded.
- `PlanQueryLimitError` (429 PLAN_QUERY_LIMIT): Monthly query quota exceeded.
- `ModelStateError` (423): Job in an invalid state for the requested action.

### Request Example
```python
from exportcomments.exceptions import (
    ExportCommentsException,
    RequestParamsError,
    AuthenticationError,
    ForbiddenError,
    ModelLimitError,
    ResourceNotFound,
    PlanRateLimitError,
    ConcurrencyRateLimitError,
    PlanQueryLimitError,
    ModelStateError,
)

from exportcomments import ExportComments

ex = ExportComments('<YOUR_API_TOKEN>')

try:
    response = ex.jobs.create(url='https://www.instagram.com/p/ABC123/')

except AuthenticationError as e:
    print(f"Auth failed [{e.status_code}]: {e.detail}")

except PlanRateLimitError as e:
    import time
    print(f"Rate limited. Waiting {e.seconds_to_wait}s...")
    time.sleep(e.seconds_to_wait)

except ForbiddenError as e:
    print(f"Forbidden [{e.error_code}]: {e.detail}")

except ExportCommentsException as e:
    # Catch-all for any other SDK exception
    print("Unexpected error:", e)
```
```

--------------------------------

### List Export Jobs

Source: https://github.com/exportcomments/exportcomments-python/blob/main/README.md

Retrieve a list of existing export jobs, with support for pagination and limiting the number of results.

```python
response = ex.jobs.list(page=1, limit=10)
jobs = response.body
```

--------------------------------

### Ping API Connectivity

Source: https://github.com/exportcomments/exportcomments-python/blob/main/README.md

Checks if the API is reachable and responsive. Returns a simple pong message.

```APIDOC
## Ping API Connectivity

### Description
Checks if the API is reachable and responsive.

### Method
`ping()`

### Request Example
```python
result = ex.ping()
print(result)
```

### Response Example
```json
{
  "message": "pong"
}
```
```

--------------------------------

### Download Raw JSON Data

Source: https://context7.com/exportcomments/exportcomments-python/llms.txt

Fetches the completed export as a parsed Python list of comment/review dicts. Each dict contains fields such as `message`, `author_name`, `date`, `likes`, etc. Internally calls `check()` to retrieve the `json_url` and returns `response.json()`.

```APIDOC
## `ex.jobs.download_json(guid)` — Download Raw JSON Data

Fetches the completed export as a parsed Python list of comment/review dicts. Each dict contains fields such as `message`, `author_name`, `date`, `likes`, etc. Internally calls `check()` to retrieve the `json_url` and returns `response.json()`.

### Parameters
- **guid** (string) - Required - The unique identifier for the export job.

### Request Example
```python
from exportcomments import ExportComments
from exportcomments.exceptions import ExportCommentsException

ex = ExportComments('<YOUR_API_TOKEN>')
guid = 'previously-returned-guid'

try:
    comments = ex.jobs.download_json(guid=guid)
    print(f"Total comments: {len(comments)}")

    for comment in comments[:5]:
        print(f"[{comment.get('date')}] {comment.get('author_name')}: {comment.get('message')}")

except ValueError as e:
    print("Job not ready (no JSON URL):", e)
except ExportCommentsException as e:
    print("API error:", e)
```

### Response
- Returns a list of dictionaries, where each dictionary represents a comment or review.
```

--------------------------------

### Download Raw JSON Data

Source: https://github.com/exportcomments/exportcomments-python/blob/main/README.md

Retrieve the exported data directly as parsed JSON for a completed job.

```python
data = ex.jobs.download_json(guid=guid)
for comment in data:
    print(comment['message'], comment['author_name'])
```

--------------------------------

### List Jobs

Source: https://github.com/exportcomments/exportcomments-python/blob/main/README.md

Retrieves a list of previously created export jobs, with support for pagination.

```APIDOC
## List Jobs

### Description
Retrieves a list of export jobs.

### Method
`jobs.list(page=1, limit=10)`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **page** (integer) - Optional - The page number to retrieve.
- **limit** (integer) - Optional - The number of jobs to return per page.

### Request Example
```python
response = ex.jobs.list(page=1, limit=10)
jobs = response.body
```

### Response
#### Success Response (200)
- **jobs** (array) - A list of job objects.

#### Response Example
```json
[
  {
    "guid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "url": "https://www.instagram.com/p/1234567",
    "status": "done"
  }
]
```
```

--------------------------------

### Download Raw JSON Data

Source: https://github.com/exportcomments/exportcomments-python/blob/main/README.md

Retrieves the exported data for a completed job directly as parsed JSON.

```APIDOC
## Download Raw JSON Data

### Description
Gets the exported data as parsed JSON.

### Method
`jobs.download_json(guid)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **guid** (string) - Required - The unique identifier of the job.

### Request Example
```python
data = ex.jobs.download_json(guid=guid)
for comment in data:
    print(comment['message'], comment['author_name'])
```

### Response
#### Success Response (200)
- **data** (array) - An array of comment objects.

#### Response Example
```json
[
  {
    "message": "Great post!",
    "author_name": "User123"
  }
]
```
```

--------------------------------

### ExportCommentsResponse Object Properties

Source: https://context7.com/exportcomments/exportcomments-python/llms.txt

Illustrates how to interact with the `ExportCommentsResponse` object. It provides access to the parsed JSON body, the number of requests made, and methods to retrieve raw successful or failed HTTP responses.

```python
from exportcomments import ExportComments

ex = ExportComments('<YOUR_API_TOKEN>')

response = ex.jobs.list(page=1, limit=5)

# .body: parsed JSON payload
print(type(response.body))         # <class 'list'> or <class 'dict'>

# .request_count: number of underlying HTTP requests made
print(response.request_count)      # 1

# Iterate over raw requests.Response objects
for raw in response:
    print(raw.status_code, raw.url)

# Access individual successful / failed responses
print(response.successful_raw_responses())
print(response.failed_raw_responses())
```

--------------------------------

### Handle ExportComments Exceptions

Source: https://github.com/exportcomments/exportcomments-python/blob/main/README.md

Catch specific exceptions like `ExportCommentsException` to handle API errors gracefully. The table lists common exception classes and their descriptions.

```python
from exportcomments.exceptions import ExportCommentsException

try:
    response = ex.jobs.create(
        url='https://www.instagram.com/p/1234567',
        options={'replies': True}
    )
except ExportCommentsException as e:
    print(e)
```

--------------------------------

### ExportCommentsResponse Object

Source: https://context7.com/exportcomments/exportcomments-python/llms.txt

Wraps raw `requests.Response` objects. The `.body` property returns the parsed JSON as a dict (single request) or a merged list (batched requests). Automatically raises a typed exception if the HTTP status code indicates an error.

```APIDOC
## `ExportCommentsResponse` — Response Object

Wraps raw `requests.Response` objects. The `.body` property returns the parsed JSON as a dict (single request) or a merged list (batched requests). Automatically raises a typed exception if the HTTP status code indicates an error.

### Properties
- **body**: The parsed JSON payload. This will be a dictionary for single responses or a list for batched responses.
- **request_count**: The number of underlying HTTP requests made to fulfill the operation.

### Methods
- `successful_raw_responses()`: Returns a list of raw `requests.Response` objects for successful requests.
- `failed_raw_responses()`: Returns a list of raw `requests.Response` objects for failed requests.

### Iteration
The response object is iterable, yielding individual raw `requests.Response` objects.

### Request Example
```python
from exportcomments import ExportComments

ex = ExportComments('<YOUR_API_TOKEN>')

response = ex.jobs.list(page=1, limit=5)

# .body: parsed JSON payload
print(type(response.body))         # <class 'list'> or <class 'dict'>

# .request_count: number of underlying HTTP requests made
print(response.request_count)      # 1

# Iterate over raw requests.Response objects
for raw in response:
    print(raw.status_code, raw.url)

# Access individual successful / failed responses
print(response.successful_raw_responses())
print(response.failed_raw_responses())
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.