Install & Compatibility
Where this runs
tested against v0.2.6 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.704s · 41.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.0s · import 0.678s · 42MB
41MB installed
● package 41MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PinterestSDKClient
✓ from pinterest.client import PinterestSDKClient
✗ import pinterest_api_sdk
The primary client class is located within the 'pinterest.client' submodule, not directly under the top-level package.
AdAccount
✓ from pinterest.ads.ad_accounts import AdAccount
✗ from pinterest.models import AdAccount
Entity models are organized under specific API domains (e.g., `pinterest.ads`).
This quickstart demonstrates how to initialize the Pinterest SDK client using environment variables and retrieve a list of accessible ad accounts. Ensure your Pinterest App ID, Secret, and an Access Token (or Refresh Token) are configured as environment variables or in a `.env` file for the `create_default_client()` method to function.
import os
from pinterest.client import PinterestSDKClient
from pinterest.ads.ad_accounts import AdAccount
# Set environment variables or create a .env file with PINTEREST_APP_ID, PINTEREST_APP_SECRET,
# PINTEREST_ACCESS_TOKEN (or PINTEREST_REFRESH_ACCESS_TOKEN if using refresh token flow).
# Example environment variables:
# os.environ['PINTEREST_APP_ID'] = 'YOUR_APP_ID'
# os.environ['PINTEREST_APP_SECRET'] = 'YOUR_APP_SECRET'
# os.environ['PINTEREST_ACCESS_TOKEN'] = 'YOUR_ACCESS_TOKEN'
# Create a default client (uses environment variables or config.json)
# For production, consider using create_client_with_refresh_token for long-lived access
try:
client = PinterestSDKClient.create_default_client()
# Example: List ad accounts
ad_accounts = AdAccount.get_all(client=client) # Pass client explicitly if not using default behavior
if ad_accounts:
print(f"Found {len(ad_accounts)} ad account(s).")
for account in ad_accounts:
print(f" Ad Account ID: {account.id}, Name: {account.name}")
else:
print("No ad accounts found or accessible.")
except Exception as e:
print(f"An error occurred: {e}")
print("Please ensure your Pinterest API credentials (APP_ID, APP_SECRET, ACCESS_TOKEN) are correctly set as environment variables or in a .env file.")
Debug
Known issues
breakingOlder versions (prior to v0.2.6) used `yaml.load`, which is insecure. This was updated to `yaml.safe_load` in v0.2.6. Applications parsing untrusted YAML with older versions may be vulnerable to arbitrary code execution.fixUpgrade to pinterest-api-sdk v0.2.6 or newer: `pip install --upgrade pinterest-api-sdk`.
affects: <0.2.6
gotchaWhen creating multiple `PinterestSDKClient` instances or not relying on the globally configured default client, you must explicitly pass the `client` object to model methods (e.g., `AdAccount.get_all(client=my_custom_client)`). Forgetting this can lead to methods attempting to use an incorrect or uninitialized default client.fixAlways pass the `client` parameter to model methods if you are not exclusively using `PinterestSDKClient.create_default_client()` and expect its scope. This behavior was clarified and fixed in v0.2.2 regarding classmethod `create`.
affects: All versions
deprecatedPinterest API v5 requires Transport Layer Security (TLS) version 1.2 or later. Older TLS protocols (1.0 and 1.1) are deprecated and will not work.fixEnsure your Python environment and underlying OS libraries support and default to TLS 1.2+ for HTTPS connections. Most modern Python installations should handle this automatically, but older systems might require updates.
affects: All versions using Pinterest API v5
gotchaUsing the `android_deep_link` field when creating an Ad via the SDK will currently generate an error as it is not yet available through the API.fixAvoid setting the `android_deep_link` parameter when creating or updating Ads through the SDK until Pinterest's API documentation indicates its availability.
affects: All versions
Errors
Common errors & fixes
pinterest.client.PinterestSDKClient.create_default_client() could not be instantiated
The SDK client could not find required authentication credentials (APP_ID, APP_SECRET, ACCESS_TOKEN/REFRESH_TOKEN) in environment variables or a `config.json` file.
fixSet `PINTEREST_APP_ID`, `PINTEREST_APP_SECRET`, and either `PINTEREST_ACCESS_TOKEN` or `PINTEREST_REFRESH_ACCESS_TOKEN` in your environment or a `.env` file. Alternatively, create a `config.json` file with these credentials.
requests.exceptions.HTTPError: 401 Client Error: Unauthorized for url: ...
The provided access token is invalid, expired, or does not have the necessary scopes for the requested API operation.
fixVerify that your access token is current and has the correct permissions (scopes) for the API endpoint you are calling. If using a refresh token, ensure it's valid to obtain a new access token. Regenerate tokens if necessary.
AttributeError: module 'pinterest' has no attribute 'client'
Attempting to import `PinterestSDKClient` incorrectly, for example, `import pinterest.client.PinterestSDKClient` or `from pinterest import PinterestSDKClient`.
fixThe correct import path for the main client is `from pinterest.client import PinterestSDKClient`.
Upgrade
Version history
0.2.6latest on PyPI · released Sep 4, 2025
Audit
Dependencies
urllib3requiredInternal HTTP request handling; version requirements were loosened in v0.2.5.
python-dotenvrequiredUsed for loading environment variables from .env files; version requirements were loosened in v0.2.5.
PyYAMLrequiredUsed for parsing YAML configurations; `yaml.safe_load` introduced in v0.2.6 for security.