Prepare your account and environment
Create a Social API account, connect a payment method for the one-time 100-credit allowance and generate an API key. Set TICKERTRENDS_API_KEY in your server environment. Keep it out of notebooks you share and source control. The example uses only Python standard-library modules.
Run a bounded request
The script requests up to 20 TikTok posts without captions, with a maximum fresh-delivery budget of one credit. It checks HTTP errors, uses a timeout and polls for at most two minutes. If processing continues, rerun with the same receipt file. Use a new receipt filename for a different query or intentional new request.
Use the same client for web search
For web search, use a separate receipt file and POST /web-search with {"query":"openai","country":"US","language":"en","limit":10,"offset":0,"max_credits":0.075}. Poll /web-search-requests/{id} every second and read results instead of posts after success. Follow pagination.next_offset with a new receipt when pagination.has_more is true. The same key and balance apply: 0.075 credit per started block of 10 returned results, or $0.75 per 1,000 searches returning 1–10 results each at the standard credit price. This endpoint is a rollout preview; handle HTTP 503 with bounded retries using the saved body and key.
Consume results deliberately
Read posts, source URLs, billing and next_cursor from the successful data object. Follow pagination only when needed, retaining filters and using a new key for each page. A partial or failed result is not proof of zero activity. Resolve 400, 402, 403 or 409 responses before retrying.
Python quickstart
Example requests require your own API key. Running a request can consume prepaid credits within the stated budget.
import json, os, time, uuid
from pathlib import Path
from urllib.request import Request, urlopen
base = "https://social.tickertrends.io/api/public"
receipt = Path("social-request.json")
if not receipt.exists():
saved = {"key": str(uuid.uuid4()), "body": {
"term": "openai", "platforms": "tiktok", "limit": 20, "max_credits": 1}}
with receipt.open("x") as output:
json.dump(saved, output)
saved = json.loads(receipt.read_text())
headers = {"X-API-Key": os.environ["TICKERTRENDS_API_KEY"],
"Idempotency-Key": saved["key"], "Content-Type": "application/json"}
request = Request(base + "/social-posts", headers=headers,
data=json.dumps(saved["body"]).encode(), method="POST")
with urlopen(request, timeout=60) as response:
data = json.load(response)["data"]
request_id = data.get("id")
deadline = time.monotonic() + 120
while data.get("status") == "processing" and time.monotonic() < deadline:
time.sleep(5)
request = Request(base + "/social-requests/" + request_id, headers=headers)
with urlopen(request, timeout=60) as response:
data = json.load(response)["data"]
print(json.dumps(data, indent=2))
# Keep social-request.json to resume safely. Inspect status before using posts.