PrimeApi Documentation - Getting Started

PrimeApi is a real-time, unofficial TikTok data API. Every request is served live with no caching, with an average response time of around 1000ms. This guide walks you through making your first call in a few minutes, from getting an API key to handling responses and errors.

Base URL

All requests are made to a single base URL. Append the endpoint path and query parameters to it:

https://api.primeapi.co/

For example, the user lookup endpoint is reached at https://api.primeapi.co/userinfo-by-username?username=taylorswift. The full list of available paths is documented on the API endpoints page.

Authentication

PrimeApi authenticates every request with an HTTP header. Send your secret key in the X-PrimeAPI-Key header on each call:

X-PrimeAPI-Key: YOUR_API_KEY

Requests without a valid key are rejected before any data is returned. Keep your key private and never expose it in client-side code that ships to end users.

Getting your API key

1. Create a free account. New accounts start with 50 free credits.
2. Confirm your email address using the link we send you.
3. Open your profile page to copy your personal API key.

Credit System

PrimeApi uses a simple credit-based model instead of complicated quotas:

• Each API request costs 1 credit. The credit is deducted the moment the request is accepted and forwarded, so a call that comes back empty, incomplete, or with an upstream error still consumes 1 credit.
• Requests we reject before forwarding do not cost credits: a missing or invalid API key, an exceeded rate limit, or an exhausted balance.
• Every new account includes 50 free credits to test the service.
• Each response includes an X-PrimeAPI-Balance header showing your remaining credit balance, so you can track usage in real time.

When you need more, you can top up on the pricing page: Basic ($9.90 / 2,500 credits), Pro ($59.90 / 50,000), Ultra ($99.90 / 150,000), and Enterprise ($279.00 / 500,000).

Payment is by cryptocurrency only, processed through Cryptomus. There is no credit card or PayPal option. Credits are added to your account automatically once the payment is confirmed on-chain.

Rate Limits

The default rate limit is 100 requests per minute per API key. If you exceed it, requests are temporarily rejected with a rate-limit message (see Error Responses). Spread bulk jobs across time or contact us through the contact page if you need a higher limit.

Your First Request

The example below calls userinfo-by-username to fetch a TikTok profile by its handle. Replace YOUR_API_KEY with the key from your profile page.

cURL

curl "https://api.primeapi.co/userinfo-by-username?username=taylorswift" \
  -H "X-PrimeAPI-Key: YOUR_API_KEY"

Node.js (Axios)

const axios = require('axios');

axios.get('https://api.primeapi.co/userinfo-by-username', {
  params: { username: 'taylorswift' },
  headers: { 'X-PrimeAPI-Key': 'YOUR_API_KEY' }
})
  .then(res => {
    console.log(res.data);
    console.log('Balance:', res.headers['x-primeapi-balance']);
  })
  .catch(err => console.error(err.response ? err.response.data : err));

Python (Requests)

import requests

url = "https://api.primeapi.co/userinfo-by-username"
params = {"username": "taylorswift"}
headers = {"X-PrimeAPI-Key": "YOUR_API_KEY"}

response = requests.get(url, params=params, headers=headers)
print(response.json())
print("Balance:", response.headers.get("X-PrimeAPI-Balance"))

Response Format

Responses are returned as JSON. The HTTP headers carry account metadata, most importantly your remaining balance:

X-PrimeAPI-Balance: 49

Decode the JSON body in your language of choice and read the fields you need (profile details, post lists, comments, and so on). Field structure varies per endpoint; you can preview the exact shape of every response on the Playground under the Example Responses tab.

Error Responses

When a request cannot be served, PrimeApi returns a JSON object with a message field. The four common cases are:

Always check for a message field in the response before assuming you received data. If you see a key error, verify the X-PrimeAPI-Key header; if the balance is exhausted, top up on the pricing page.

Next Steps

• Browse all 30 endpoints across 8 categories on the API endpoints page.
• Test any endpoint live, with code generated in 14 languages, in the Playground.
• Explore real-world workflows on the use cases page.