TrendsAGI Official Python Client

About

Connect your paid social and search workflows to live market signals.

trendsagi is a BYOC-first SDK: TrendsAGI provides intelligence (/api/trends, /api/trends/{id}/ai-insights), and you execute Google/Meta/TikTok/LinkedIn updates from your own infrastructure with runtime credentials.

Plan Notes (API Access)

Developer plan includes:
- 1 API integration connection
- 100 API calls/day included
- Overage billing above included daily usage
Advantage/Scale unlock higher daily API limits, more keys, and expanded team workflows.

Resources

API Docs: https://trendsagi.com/api-docs
Endpoint Reference: https://trendsagi.com/api-docs#endpoints
BYOC Integrations Guide (repo): INTEGRATIONS_BYOC.md

Installation

pip install trendsagi

Quick Start (BYOC Execution)

import os
from trendsagi import TrendsAGIClient
from trendsagi.integrations import GoogleAdsExecutor

client = TrendsAGIClient(api_key=os.getenv("TRENDSAGI_API_KEY"))

# 1) Discover a real trend and read its cached insight
trends = client.get_trends(limit=5)
trend = next((item for item in trends.trends if item.id is not None), None)
if trend is None:
    raise RuntimeError("No trend is available in this window")
insight = client.get_ai_insights(trend_id=trend.id)
if not insight:
    raise RuntimeError("AI insight not ready yet")

# 2) Execute in your own runtime (credentials stay with you)
google = GoogleAdsExecutor(
    {
        "access_token": os.environ["GOOGLE_ADS_ACCESS_TOKEN"],
        "developer_token": os.environ["GOOGLE_ADS_DEVELOPER_TOKEN"],
    }
)

# 3) Preview only; inspect the result before any explicit execution
preview = google.apply_targeting(
    insight,
    customer_id="1234567890",
    campaign_id="9876543210",
    dry_run=True,
    strict_mode=True,
)
print(preview.response)

Evidence-backed recommendations

Recommendations include an optional decision brief that explains why an action is timely, the measured signals behind it, expected benefit, urgency, and concrete next steps. The confidence score measures evidence completeness; it is not a prediction of business outcomes.

recommendations = client.get_recommendations(
    match_user_interests=True,
    priority="high",
    sort="priority",
    limit=10,
)

for recommendation in recommendations.recommendations:
    brief = recommendation.decision_brief
    if brief is None:
        # Compatible with API deployments that predate decision briefs.
        continue

    print(recommendation.title, brief.confidence.score, brief.why_now)
    if brief.actionable and brief.next_steps:
        print("Next step:", brief.next_steps[0])
    else:
        print("Verify first; missing:", ", ".join(brief.data_quality.missing_signals))

Use actionable and data_quality to degrade honestly when a trend is stale or supporting signals are incomplete. The API returns HTTP 409 if a client attempts to mark a recommendation actioned while its current brief is not actionable.

Supported Integrations

GoogleAdsExecutor
MetaAdsExecutor
TikTokAdsExecutor
LinkedInAdsExecutor

All integrations support:

runtime-supplied credentials
deterministic idempotency keys
dry-run previews (dry_run=True)
strict validation (strict_mode=True)

Core Endpoints Used by Integrations

GET /api/trends
GET /api/trends/{trend_id}/ai-insights
POST /api/trends/{trend_id}/ai-insights/generate
GET /api/trends/ai-insights/status/{task_id}
GET /api/intelligence/recommendations

For full request/response contracts and all other endpoints, use the API docs link above.

The legacy crisis-event list and acknowledge/archive methods remain available for accounts entitled to the existing crisis feature. The resilience beta's event evidence, reviews, exports, source status, and location methods from version 0.10.0 have been withdrawn and are no longer supported by the current API.

CLI Scaffolder

# Docker template
trendsagi scaffold --type docker --output ./runner

# Terraform template
trendsagi scaffold --type terraform --output ./infra

Error Handling

from trendsagi import exceptions

try:
    client.get_trends(limit=5)
except exceptions.RateLimitError:
    print("Rate limited; retry with backoff")
except exceptions.AuthenticationError:
    print("Invalid API key")

Metadata

Release files for trendsagi 0.11.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for trendsagi 0.11.0
File	Size	Uploaded	Provenance
trendsagi-0.11.0.tar.gz	34.2 kB	Oct 2, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for trendsagi 0.11.0
File	Interpreter	ABI	Platform	Reset
trendsagi-0.11.0-py3-none-any.whl 33.0 kB Oct 2, 2026 Without provenance	Python 3	none	any	Details

Total release size: 67.1 kB

Release files / trendsagi-0.11.0.tar.gz

Download URL	trendsagi-0.11.0.tar.gz
Size	34.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`675951b278db92cf326fe99090ceab3fa5765ef47bc0b9bd8415e2c8bdb03cab`
BLAKE2b-256 checksum How to use checksums	`2050af0afae3c84220ca603b44414ecdbf7d559e212b4de00b6b60a30a33694e`
Upload date	Oct 2, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.6`

Release files / trendsagi-0.11.0-py3-none-any.whl

Download URL	trendsagi-0.11.0-py3-none-any.whl
Size	33.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`4b52f63e4a8a45f05d4e637b8e0d52964db473162cfb3d15e95248edb8a49b7b`
BLAKE2b-256 checksum How to use checksums	`c3508cb40c86ed72a4429b81eee0203971ea833865e05ae3ffa72441b4a89562`
Upload date	Oct 2, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.6`

Security for trendsagi 0.11.0

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.