# API Keys (/api-keys)
API keys authenticate your requests to the API. You manage them entirely from the dashboard: set a category, restrict usage with rolling quotas, add an expiry date, and monitor activity per key through request logs.
For how to include a key in a request, see the [Introduction](/introduction).
## Creating a key [#creating-a-key]
### Open the form [#open-the-form]
Go to [dashboard → API Keys → New](https://app.chartquery.com).
### Fill in the fields [#fill-in-the-fields]
Give the key an **alias** (unique label for your own reference), pick a **category**, and optionally configure quotas and an expiry date.
### Copy the secret [#copy-the-secret]
After saving, the secret is shown **once**. Copy it immediately and store it in an environment variable. It cannot be retrieved again.
## Key fields [#key-fields]
| Field | Description |
| ------------------ | ------------------------------------------------------------------------------------------------ |
| **Alias** | Unique label per account. Shows up in logs and dashboard filters. |
| **Category** | Organizational tag (see [Categories](#categories)). Has no effect on API behavior. |
| **Active** | Enables or disables the key. Inactive keys are rejected immediately with `401 Inactive API Key`. |
| **Expires** | Optional date after which the key stops working. Leave blank for no expiry. |
| **Request quotas** | Optional per-key caps on rolling time windows (see [Per-key quotas](#per-key-quotas)). |
## Categories [#categories]
Categories tag keys for your own organization. They appear in dashboard filters and analytics but do not change how the API processes a request.
| Category | Typical use |
| ------------- | --------------------------------------------------- |
| `production` | Live traffic, customer-facing systems |
| `development` | Local development and testing |
| `staging` | Pre-production and CI environments |
| Custom | Any free-text label, e.g. `sandbox`, `partner-acme` |
Keep one key per environment so you can revoke or rotate it independently.
## Per-key quotas [#per-key-quotas]
Each key can have independent hard caps on request volume, enforced on rolling windows (not calendar boundaries):
| Quota | Window |
| ----------- | ----------------------------------------------------- |
| **Total** | All-time: the key is blocked permanently once reached |
| **Daily** | Last 24 hours (rolling, not midnight-to-midnight) |
| **Weekly** | Last 7 days (rolling) |
| **Monthly** | Last 30 days (rolling) |
Leave a field blank to apply no cap for that window. When a quota is reached, the API returns `401` with `Rate limit exceeded for the API key:` and the quota name in the message:
```json
{ "error": "Rate limit exceeded for the API key: quota total" }
```
```json
{ "error": "Rate limit exceeded for the API key: quota daily" }
```
```json
{ "error": "Rate limit exceeded for the API key: quota weekly" }
```
```json
{ "error": "Rate limit exceeded for the API key: quota monthly" }
```
Quota counts are aggregated from request logs and cached for up to 24 hours. Enforcement is accurate within that window, not to the exact request.
Per-key quotas are distinct from **plan-level rate limits** (per-second and per-minute caps that apply account-wide). Both return `401`, with a message that names the limit you reached. See [Error Handling](/error-handling) for details.
## Expiry [#expiry]
Set an expiry date on keys used in scripts, CI pipelines, or partner integrations. Once the date passes, the API returns:
```json
{ "error": "Expired API Key" }
```
HTTP status `401`. Create and deploy a replacement key before the expiry date to avoid any downtime.
## Request logs [#request-logs]
Every request made with a key is recorded under **API Keys → Logs** in the dashboard. Each entry shows:
| Field | Description |
| -------- | -------------------------------- |
| Endpoint | HTTP method and path |
| Status | Response status code |
| Duration | Time to first byte (ms) |
| IP | Caller IP address |
| Credits | Credits charged for this request |
Use logs to audit activity per key, debug unexpected errors, or identify traffic from compromised keys.
## Deactivating vs. deleting [#deactivating-vs-deleting]
| Action | Effect |
| -------------- | ---------------------------------------------------------------------------------------------------- |
| **Deactivate** | Key is blocked immediately. Usage history and settings are kept. Can be reactivated. |
| **Delete** | Permanently removes the key and its configuration. Only possible if the key has **never been used**. |
Prefer deactivation over deletion. If a key has request history, it cannot be deleted. The history is retained for billing and auditing.
## Rotating a key [#rotating-a-key]
### Create the replacement [#create-the-replacement]
Go to [dashboard → API Keys → New](https://app.chartquery.com) and create a new key with the same category and quota settings. Give it a new alias to distinguish it.
### Deploy the new key [#deploy-the-new-key]
Update the environment variable in every system that uses the old key and redeploy.
### Deactivate the old key [#deactivate-the-old-key]
Set the old key to **inactive** in the dashboard. This blocks any remaining requests without removing its history.
## Error reference [#error-reference]
| Error | Status | Cause |
| ---------------------------------------------------------------------------- | ------ | ---------------------------------------------- |
| `Invalid API Key` | 401 | Key not found or malformed |
| `Inactive API Key` | 401 | Key is disabled |
| `Expired API Key` | 401 | Key has passed its expiry date |
| `Rate limit exceeded for the API key: quota …` | 401 | Per-key rolling quota reached |
| `Rate limit exceeded: You've exceeded the … rate limit on your subscription` | 401 | Plan-level per-second or per-minute cap |
| `IP temporarily blocked` | 403 | Too many failed auth attempts from the same IP |
***
See also: [Best Practices](/best-practices) for security guidelines and [Glossary](/glossary) for term definitions.
# Auto Top-Up (/auto-top-up)
Never run out of capacity mid-workflow. Auto Top-Up monitors your remaining balance (API quota + extra credits) and purchases a selected one-time pack on your behalf when your balance drops below a configurable threshold.
## How it works [#how-it-works]
### Set a threshold [#set-a-threshold]
Choose the percentage of your remaining balance (API quota + extra credits) at which the automatic purchase should trigger. When your balance falls below this level, Auto Top-Up activates.
### Pick a one-time pack [#pick-a-one-time-pack]
Select the one-time pack to purchase automatically. Depending on the product, this adds API quota or extra credits. The pack is charged to the payment method on file in your account.
### Capacity is added instantly [#capacity-is-added-instantly]
Once the purchase completes, the API quota or extra credits are available immediately. No downtime, no failed requests.
## Enabling Auto Top-Up [#enabling-auto-top-up]
1. Go to **[Settings → Subscription](https://app.chartquery.com)** in your dashboard.
2. Open the **Auto Top-Up** section.
3. Toggle **Enable** and choose a one-time pack (API top-up or extra credits) and a threshold percentage.
4. Click **Save** to activate.
Auto Top-Up is only available on paid plans. Users on the Free plan cannot enable automatic purchases.
## Configuration options [#configuration-options]
| Option | Description |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **One-time pack** | The product purchased automatically when the threshold is reached (API top-up or extra credits). |
| **Threshold (%)** | The percentage of your remaining balance (API quota + extra credits) that triggers the top-up. Accepts values between 10% and 30%. |
## Billing [#billing]
Automatic purchases are charged to the payment method associated with your account. You will receive an invoice by email for each automatic purchase, just like a manual credit purchase.
Make sure your payment method is up to date. If a charge fails, Auto Top-Up is automatically **disabled** on your account to prevent repeated failed attempts. You will need to re-enable it manually once your payment method is updated.
## Built-in protections [#built-in-protections]
Auto Top-Up includes two safeguards to prevent unexpected charges:
| Protection | How it works |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Threshold-only trigger** | A purchase only fires when your remaining balance drops below the configured percentage. It never runs on a fixed schedule or at a specific time. |
| **72-hour cooldown** | After a top-up completes, the system waits at least 72 hours before it can trigger again, even if your balance drops below the threshold a second time during that window. |
| **Auto-disable on failure** | If the Stripe charge fails, Auto Top-Up is automatically disabled to protect your account from repeated failed payment attempts. |
## Frequently asked questions [#frequently-asked-questions]
### Will I be charged immediately when I enable Auto Top-Up? [#will-i-be-charged-immediately-when-i-enable-auto-top-up]
No. Enabling Auto Top-Up does not trigger a purchase. The charge only fires when your balance actually drops below the configured threshold.
### Can I be charged multiple times in a short period? [#can-i-be-charged-multiple-times-in-a-short-period]
No. A built-in 72-hour cooldown prevents more than one automatic purchase from firing within any 72-hour window, regardless of how your balance fluctuates.
### Can I disable Auto Top-Up at any time? [#can-i-disable-auto-top-up-at-any-time]
Yes. Toggle the **Enable** switch off in **Settings → Subscription → Auto Top-Up** and save. No further automatic purchases will occur.
### What happens if my payment fails? [#what-happens-if-my-payment-fails]
Auto Top-Up is automatically disabled on your account. You will need to update your payment method and re-enable the feature manually from your subscription settings.
### Is Auto Top-Up available on the Free plan? [#is-auto-top-up-available-on-the-free-plan]
No. You need an active paid subscription to enable automatic credit top-ups.
# Best Practices (/best-practices)
Follow these guidelines to build integrations that are reliable, cost-efficient, and easy to maintain.
## Credit efficiency [#credit-efficiency]
### Check your balance before large batches [#check-your-balance-before-large-batches]
Before triggering a high-volume operation, verify you have enough credits. The [Usage](/usage) endpoint is free and returns your current balance in real time.
```bash
curl "https://api.chartquery.com/v1/usage" \
-H "x-api-key: YOUR_API_KEY"
```
Enable [Auto Top-Up](/auto-top-up) to automatically refill your balance when it drops below a threshold, so your workflows keep running without interruption.
### Avoid redundant calls [#avoid-redundant-calls]
Cache results on your side whenever the underlying data is unlikely to change between requests. Re-fetching identical inputs wastes credits.
```typescript
const cache = new Map()
async function fetchCached(key: string, fetcher: () => Promise) {
if (cache.has(key)) return cache.get(key)
const result = await fetcher()
cache.set(key, result)
return result
}
```
### Only call what you need [#only-call-what-you-need]
Each endpoint has a defined credit cost listed on the [Credits](/credits) page. Prefer lighter endpoints when a full response is not required.
***
## Authentication [#authentication]
### Store keys in environment variables [#store-keys-in-environment-variables]
Never hardcode your API key in source code. Use environment variables and load them at runtime.
```typescript
const apiKey = process.env.CHARTQUERY_API_KEY
if (!apiKey) throw new Error("API key is not set")
```
```python
import os
api_key = os.environ["CHARTQUERY_API_KEY"]
```
```php
$apiKey = getenv('CHARTQUERY_API_KEY');
```
```go
apiKey := os.Getenv("CHARTQUERY_API_KEY")
```
### Use separate keys per environment [#use-separate-keys-per-environment]
Create distinct API keys for development, staging, and production in your [dashboard](https://app.chartquery.com). This lets you revoke or rotate a compromised key without affecting other environments.
| Environment | Recommended category |
| ------------ | -------------------- |
| Local dev | `development` |
| CI / staging | `development` |
| Production | `production` |
### Rotate keys periodically [#rotate-keys-periodically]
Treat API keys like passwords. Set an expiry date on sensitive keys and rotate them on a regular schedule from the API Keys section of your account settings.
Never expose your API key in client-side code, browser requests, or public repositories. Always proxy calls through your own backend.
***
## Error handling [#error-handling]
### Always check the HTTP status code [#always-check-the-http-status-code]
Do not assume a request succeeded. Every response should be checked against its HTTP status code before processing the body. See the [Error Handling](/error-handling) guide for a full breakdown.
### Retry on transient errors [#retry-on-transient-errors]
Server errors (`500`) and network timeouts are transient. Implement exponential backoff to retry automatically:
```typescript
async function fetchWithRetry(url: string, options: RequestInit, maxRetries = 3) {
for (let attempt = 0; attempt <= maxRetries; attempt++) {
try {
const res = await fetch(url, options)
if (res.status === 500 && attempt < maxRetries) {
await new Promise(r => setTimeout(r, 500 * 2 ** attempt))
continue
}
return res
} catch {
if (attempt === maxRetries) throw new Error("Max retries reached")
await new Promise(r => setTimeout(r, 500 * 2 ** attempt))
}
}
}
```
### Never retry on `402` without topping up [#never-retry-on-402-without-topping-up]
A `402` with `Payment required`, an open-invoice message, or `Insufficient credits: …` means the call was not executed. Retrying immediately will not help. Add capacity from your [dashboard](https://app.chartquery.com) (top-up or plan upgrade), settle open invoices, or enable [Auto Top-Up](/auto-top-up).
***
## Rate limits [#rate-limits]
### Spread requests over time [#spread-requests-over-time]
If you need to send a large number of calls, distribute them across time rather than firing them all at once. A simple delay between iterations prevents hitting rate limits.
```typescript
const DELAY_MS = 100 // adjust based on your plan
for (const item of items) {
await processItem(item)
await new Promise(r => setTimeout(r, DELAY_MS))
}
```
### Monitor the `401` `Rate limit exceeded` response [#monitor-the-401-rate-limit-exceeded-response]
When rate-limited, the API returns `401` with a `Rate limit exceeded…` message (plan per-second/per-minute caps or a per-key quota). Back off and wait before retrying. Consider upgrading your plan or raising the key's quotas if you hit this regularly. The public API does **not** use HTTP `429` for these limits.
***
## Security [#security]
### Never make API calls from the browser [#never-make-api-calls-from-the-browser]
Your API key would be visible to anyone who inspects the network tab. Always route calls through your own server.
```
Browser → Your backend → Chartquery API
```
### Validate and sanitize inputs [#validate-and-sanitize-inputs]
If your application accepts user-supplied parameters that are passed to the API (URLs, search queries, etc.), sanitize them to prevent injection or unexpected behavior.
***
## Monitoring [#monitoring]
### Track credit consumption [#track-credit-consumption]
Query the [Usage](/usage) endpoint on a schedule (e.g. daily) and alert when consumption exceeds a threshold. This prevents surprises at the end of a billing period.
| Metric | Why it matters |
| --------------------------- | -------------------------------- |
| `remaining` | Warns you before credits run out |
| `subscription.percent_used` | Tracks your plan utilization |
| `credits.remaining` | Monitors extra credit balance |
### Log request context [#log-request-context]
Store the HTTP status code and a timestamp for every API call. This makes it easy to audit credit consumption and debug failures after the fact.
```typescript
async function apiCall(endpoint: string, params: Record) {
const url = new URL(`https://api.chartquery.com${endpoint}`)
Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v))
const res = await fetch(url.toString(), {
headers: { "x-api-key": process.env.API_KEY! },
})
console.log(JSON.stringify({
endpoint,
status: res.status,
billed: res.status === 200 || res.status === 201,
timestamp: new Date().toISOString(),
}))
return res
}
```
***
## Checklist [#checklist]
Use this checklist before going to production:
* [ ] API key stored in an environment variable, not in source code
* [ ] Separate keys for development and production
* [ ] HTTP status codes checked on every response
* [ ] Retry logic with exponential backoff for `500` errors
* [ ] No retries on `402` without adding credits first
* [ ] Rate limit handling in place
* [ ] Credit balance monitored and alerts configured
* [ ] Auto Top-Up enabled (or a manual top-up process defined)
* [ ] All API calls proxied through your backend
***
See also: [Error Handling](/error-handling) for a complete list of status codes and [Glossary](/glossary) for term definitions.
# Credits (/credits)
Each API call consumes credits from your account based on the endpoint cost. The table below lists every endpoint and its cost per successful request.
## Account balances [#account-balances]
Your account tracks two separate balances:
**API quota** combines your subscription allowance (renewed each billing period) and any remaining one-time top-ups. Subscription quota resets each billing period; top-ups are purchased once and consumed over time—they do not reset monthly. Calls consume subscription quota first, then top-ups.
**Extra credits** are a separate balance used only after API quota (subscription + top-ups) is fully exhausted. They do not reset monthly. You may receive them from onboarding rewards or manual extra-credit purchases.
Monitor both balances from the [Usage](/usage) endpoint or your dashboard sidebar. See the [Glossary](/glossary) for full definitions.
You are charged for successful requests: `200` for synchronous calls and `201` for async jobs. `404` billing is endpoint-specific (check each endpoint page). All other responses (4xx, 5xx) are free.
| Endpoint | Method | Path | Credits |
| ------------------------------------ | ------ | ------------------------- | ------- |
| [Barcode](/barcode) | `GET` | `/v1/barcode` | 3 |
| [Chart](/chart) | `GET` | `/v1/chart` | 5 |
| [Chart AI](/chart-ai) | `GET` | `/v1/chart/ai` | 10 |
| [Chart Render](/chart-render-id) | `GET` | `/v1/chart/render/{id}` | 0 |
| [Chart View](/chart-view-id) | `GET` | `/v1/chart/view/{id}` | 0 |
| [Diagram](/diagram) | `GET` | `/v1/diagram` | 5 |
| [Diagram AI](/diagram-ai) | `GET` | `/v1/diagram/ai` | 10 |
| [Diagram Render](/diagram-render-id) | `GET` | `/v1/diagram/render/{id}` | 0 |
| [Diagram View](/diagram-view-id) | `GET` | `/v1/diagram/view/{id}` | 0 |
| [Label Preview](/label) | `GET` | `/v1/label` | 3 |
| [Label Render](/label-render-id) | `GET` | `/v1/label/render/{id}` | 0 |
| [Label View](/label-view-id) | `GET` | `/v1/label/view/{id}` | 0 |
| [QR Code](/qrcode) | `GET` | `/v1/qrcode` | 3 |
| [Stats](/stats) | `GET` | `/v1/stats` | 0 |
| [Usage](/usage) | `GET` | `/v1/usage` | 0 |
# Error Handling (/error-handling)
Every request to the Chartquery API returns a standard HTTP status code. This guide covers what each code means, when credits are consumed, and how to handle failures in your integration.
## Response format [#response-format]
Successful responses return a JSON object with the data for that endpoint. Error responses follow a consistent structure:
```json
{
"error": "Human-readable description of what went wrong"
}
```
Always check the HTTP status code **before** reading the body.
***
## Status codes [#status-codes]
### `200` Success [#200-success]
**Billed.** The request completed successfully. Credits are deducted from your balance.
```typescript
const res = await fetch(url, { headers: { "x-api-key": API_KEY } })
if (res.status === 200) {
const data = await res.json()
// process data
}
```
### `201` Job Created [#201-job-created]
**Billed.** An asynchronous job was created and accepted. Your balance is checked before the job is queued, so a job never starts without the credits to pay for it.
### `202` Accepted (async) [#202-accepted-async]
**Not billed.** The request was accepted and queued for processing. Use the returned job ID to poll for the result — polling the job status is free.
### `400` Bad Request [#400-bad-request]
**Not billed.** Your request contains invalid or missing parameters.
**Common causes:**
* A required query parameter is missing
* A parameter value has the wrong type or format
* The request body is malformed
**What to do:** Re-read the endpoint documentation and verify every required parameter. Log the full request URL to spot typos.
```typescript
if (res.status === 400) {
const { error } = await res.json()
console.error("Bad request:", error)
// do not retry, fix the parameters first
}
```
### `401` Unauthorized [#401-unauthorized]
**Not billed.** Returned for authentication issues **and** rate limiting. Check the error message to distinguish between them.
Your `x-api-key` header is missing or contains an unrecognized value.
**Fix:** Copy your key from your [dashboard → API Keys](https://app.chartquery.com) and make sure the `x-api-key` header is present on every request.
The key exists but has been deactivated.
**Fix:** Go to your [dashboard → API Keys](https://app.chartquery.com) and activate the key, or generate a new one.
The key has passed its expiry date.
**Fix:** Generate a new key or extend the expiry from your dashboard.
You have sent too many requests in a short window. Plan limits look like `Rate limit exceeded: You've exceeded the … rate limit on your subscription`. Per-key quotas look like `Rate limit exceeded for the API key: quota daily` (or `total` / `weekly` / `monthly`).
**Fix:** Back off and retry after a delay. If you hit this regularly, upgrade your plan or raise the key's quotas. These limits return `401`, not `429`.
```typescript
if (res.status === 401) {
const { error } = await res.json()
if (error.toLowerCase().includes("rate limit")) {
await new Promise(r => setTimeout(r, 2000))
// retry
}
}
```
### `402` Payment required [#402-payment-required]
**Not billed.** The request was not executed. The `error` string tells you why:
* `Payment required` — API quota and pay-as-you-go credits cannot cover the call
* `You have open invoices: …` — an unpaid invoice is blocking the account
* `Insufficient credits: X required, Y available` — a per-row endpoint would return more rows than you can afford
**What to do:**
1. Purchase a top-up or upgrade your plan from your [dashboard](https://app.chartquery.com), or settle open invoices under **Settings → Invoices**.
2. Or enable [Auto Top-Up](/auto-top-up) to prevent balance exhaustion from happening again.
Auto Top-Up only triggers when your balance drops below the configured threshold. It never runs on a fixed schedule or at a specific time. A built-in **72-hour cooldown** also prevents multiple charges in a short period: once a top-up fires, it cannot trigger again for 72 hours regardless of how your balance moves. If a charge fails, Auto Top-Up is automatically disabled to protect your account.
Do not retry a `402` response immediately. The call will fail again until you add credits. Set up an alert so your team is notified when this happens.
```typescript
if (res.status === 402) {
// alert your team or trigger an auto top-up flow
throw new Error("Insufficient credits. Top up at https://app.chartquery.com")
}
```
### `403` Forbidden [#403-forbidden]
**Not billed.** The request was refused before it ran. The usual causes are an endpoint that does not exist on your plan, a deactivated account, or an IP temporarily blocked after repeated failed authentications.
**What to do:** Check the endpoint path against the reference, then confirm your account is active in the dashboard. Contact support if you believe this is a mistake.
### `404` Not Found [#404-not-found]
**May be billed** (endpoint-specific). The resource was not found. Check the individual endpoint documentation to confirm whether this response is charged.
```typescript
if (res.status === 404) {
// handle "no result" gracefully, not as a fatal error
return null
}
```
### `500` Internal Server Error [#500-internal-server-error]
**Not billed.** An unexpected error occurred on our side.
**What to do:** Retry with exponential backoff. If the issue persists, contact support.
```typescript
async function fetchWithRetry(url: string, options: RequestInit, maxRetries = 3) {
for (let attempt = 0; attempt <= maxRetries; attempt++) {
const res = await fetch(url, options)
if (res.status !== 500 || attempt === maxRetries) return res
const delay = 500 * 2 ** attempt
console.warn(`500 error, retrying in ${delay}ms (attempt ${attempt + 1}/${maxRetries})`)
await new Promise(r => setTimeout(r, delay))
}
}
```
***
## Complete error handler [#complete-error-handler]
A single function that covers every status code:
```typescript
interface ApiResult {
data: T | null
error: string | null
status: number
billed: boolean
}
async function apiCall(url: string, apiKey: string): Promise> {
const res = await fetch(url, {
headers: { "x-api-key": apiKey },
})
// 200 and 201 are always billed; 404 billing is endpoint-specific
const billed = res.status === 200 || res.status === 201
if (res.status === 200) {
return { data: await res.json() as T, error: null, status: 200, billed }
}
const body = await res.json().catch(() => ({ error: "Unknown error" }))
const error = body?.error ?? "Unknown error"
switch (res.status) {
case 400:
console.error("[400] Bad request, fix your parameters:", error)
break
case 401:
if (error.toLowerCase().includes("rate limit")) {
console.warn("[401] Rate limit, back off and retry")
} else {
console.error("[401] Auth error, check your API key:", error)
}
break
case 402:
console.error("[402] No credits remaining. Top up at https://app.chartquery.com")
break
case 403:
console.error("[403] Forbidden, check your key permissions")
break
case 404:
console.warn("[404] Not found, no result for this request")
break
case 500:
console.error("[500] Server error, retry with backoff")
break
default:
console.error(`[${res.status}] Unexpected status:`, error)
}
return { data: null, error, status: res.status, billed }
}
```
***
## Retry strategy [#retry-strategy]
| Status | Retry? | Strategy |
| ------------------ | ------ | ------------------------------------ |
| `400` | No | Fix the request first |
| `401` (rate limit) | Yes | Wait 2–5 s, then retry |
| `401` (auth) | No | Fix the API key |
| `402` | No | Add credits or settle invoices first |
| `403` | No | Check permissions |
| `404` | No | Handle as empty result |
| `500` | Yes | Exponential backoff (max 3 attempts) |
***
## Billing summary [#billing-summary]
| Status | Billed |
| --------------- | ------------------------------------------- |
| `200` | Yes |
| `201` | Yes |
| `404` | Endpoint-specific (check the endpoint docs) |
| All other codes | No |
See the [Credits](/credits) page for a full cost breakdown per endpoint. For broader integration advice, see [Best Practices](/best-practices).
# Global Parameters (/global-parameters)
These parameters can be used with any API endpoint.
| Parameter | Type | Default | Description |
| ----------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
| `x_api_key` | `string` | - | Authentication key required for all requests. Pass it in the `x-api-key` header or as a query string. |
| `soft_fail` | `boolean` | `false` | When `true`, the API returns HTTP 200 even when an error occurs. Errors are still tracked and billed normally. |
| `is_async` | `boolean` | `false` | When `true`, the request is processed asynchronously. The response contains a `job_id` that you poll on `/jobs/{job_id}`. |
| `fields` | `string` | - | Comma-separated list of fields to include in the response. Supports nested fields with dot notation. |
## Fields filtering [#fields-filtering]
Use the `fields` parameter to keep only the data you actually need in the response. This makes responses smaller, faster to download and easier to parse on your side. It is especially useful when your platform enforces a payload size limit (Make.com, Zapier, low-memory Lambdas, etc.).
### Syntax [#syntax]
Pass `fields` as a comma-separated list of field names. Use a dot (`.`) to drill into nested objects.
* Top-level fields are listed by name: `fields=name,founded`.
* Nested fields use dot notation: `fields=address.city,address.country`.
* Whitespace around commas is ignored: `fields=name, founded` works the same.
* Unknown field names are silently ignored, no error is returned.
### Selecting top-level fields [#selecting-top-level-fields]
Keep only the top-level keys you care about. The original structure is preserved for the kept fields.
```bash
curl -X GET "https://api.chartquery.com/{endpoint}?param=value&fields=name,founded,tagline" \
-H "x-api-key: YOUR_API_KEY"
```
**Response:**
```json
{
"name": "Example",
"founded": "2020",
"tagline": "Just an example"
}
```
### Selecting nested fields [#selecting-nested-fields]
Use dot notation to reach into nested objects. Only the requested subfields are returned, the rest of the parent object is dropped. Dot notation also works for objects inside arrays: `?fields=team.name` keeps the `name` of every item in `team`.
```bash
curl -X GET "https://api.chartquery.com/{endpoint}?param=value&fields=name,location.city,location.country" \
-H "x-api-key: YOUR_API_KEY"
```
**Response:**
```json
{
"name": "Example",
"location": {
"city": "Paris",
"country": "France"
}
}
```
### Good to know [#good-to-know]
* Filtering happens **after** the data is fetched: it does **not** reduce the credit cost of the call. It does reduce response size, parsing time and bandwidth.
* Top-level keys not listed in `fields` are removed from the response. Listing nested fields automatically keeps their parent object.
* Combine `fields` freely with other parameters such as `soft_fail` or `is_async`.
## Soft fail mode [#soft-fail-mode]
Handle errors gracefully by always receiving a 200 status code.
Add `soft_fail=true` to any request to receive HTTP 200 even when an error occurs.
Errors are still tracked in your dashboard and billed according to standard rules.
### Use cases [#use-cases]
* Systems that treat non-200 codes as fatal (Make.com, Zapier)
* Custom error handling in your application
* Consistent error handling across integrations
**Note for Make.com users:** by default, Make.com scenarios stop with an error when they receive a `404` or `500` HTTP status code. Using `soft_fail=true` ensures your scenario keeps running even when the API returns an error, so you can handle it gracefully in subsequent modules.
### Example [#example]
```bash
curl -X GET "https://api.chartquery.com/{endpoint}?param=invalid&soft_fail=true" \
-H "x-api-key: YOUR_API_KEY"
```
```json
{
"error": "Not Found"
}
```
## Async mode [#async-mode]
For long-running requests, use async mode to avoid timeouts.
Add `is_async=true` to receive a `job_id` immediately.
### How it works [#how-it-works]
1. Send the request with `is_async=true`
2. Receive a `job_id`
3. Poll `/jobs/{job_id}` to retrieve the result
```bash
# Step 1: start the job
curl -X GET "https://api.chartquery.com/{endpoint}?param=value&is_async=true" \
-H "x-api-key: YOUR_API_KEY"
# Response: { "job_id": "abc123..." }
# Step 2: retrieve the result
curl -X GET "https://api.chartquery.com/jobs/abc123..." \
-H "x-api-key: YOUR_API_KEY"
```
See [Status Codes](/status-codes) for response codes, [Best Practices](/best-practices) for integration guidance, and [Error Handling](/error-handling) for retry strategies.
# Glossary (/glossary)
A reference for the terms you will encounter in the documentation, dashboard, and API responses.
***
## Account [#account]
See [Tenant](#tenant).
***
## API key [#api-key]
A secret string used to authenticate API requests. Each key belongs to a tenant and has an alias, category, optional quotas, and an optional expiry date. Passed via the `x-api-key` header or `x_api_key` query parameter.
See [API Keys](/api-keys) for full details.
***
## API top-up [#api-top-up]
A one-time purchase that adds consumable API quota. Top-ups do not reset each billing period. API calls consume subscription quota first, then top-up capacity until exhausted.
Purchase top-ups from your dashboard billing section or pricing page.
***
## Alias [#alias]
The human-readable name of an API key, unique within a tenant. Used to identify keys in the dashboard and analytics.
***
## Auto Top-Up [#auto-top-up]
A feature that automatically purchases a one-time pack when your remaining balance (API quota + extra credits) drops below a configured threshold. Protected by a 72-hour cooldown between purchases. Requires an active paid subscription.
See [Auto Top-Up](/auto-top-up) for full details.
***
## Billing period [#billing-period]
The active subscription window used to measure quota consumption. Determined by the `currentPeriodStart` and `currentPeriodEnd` fields from Stripe. If no active subscription is found, the billing period defaults to the current calendar month.
***
## Category [#category]
A label on an API key (`production`, `development`, `staging`, or custom). Used for filtering and organization in the dashboard. Does not change how the API processes the request.
***
## Credit [#credit]
The unit of API consumption. Each billable request deducts a number of credits determined by the endpoint's cost. Credits are stored as ledger entries: a negative amount means credits were granted, a positive amount means they were consumed.
See [Credits](/credits) for the cost per endpoint.
***
## Extra credits [#extra-credits]
Credits stored in a separate ledger, distinct from API quota. Used only after your combined API quota (subscription + top-ups) is fully exhausted. They do not reset at the end of a billing period. Sources include onboarding rewards and manual extra-credit purchases.
***
## Per-key quota [#per-key-quota]
An optional request limit set on a specific API key. Enforced on rolling time windows: all-time total, last 24 hours, last 7 days, and last 30 days. Independent of the subscription quota.
***
## Plan [#plan]
A subscription product (e.g. "Starter", "Pro") that defines a set of features: API call quota, rate limits, access to extra credits, and more. A tenant can hold multiple active plan products simultaneously.
***
## Quota [#quota]
Your combined API call budget from subscription allowance and any remaining one-time top-ups. Weighted by per-endpoint credit cost. Subscription portion resets each billing period; top-ups are consumed once. When API quota is exhausted, extra credits are used if available; otherwise requests return `402`.
***
## Rate limit [#rate-limit]
There are two separate rate-limiting systems. **Plan limits** (per second / per minute) apply to all keys on an account and are set by the subscription plan. **Per-key quotas** (total / daily / weekly / monthly rolling windows) are optional hard caps configured per key. Both return `401` with a `Rate limit exceeded` message — the message tells you which one you hit. See [API Keys](/api-keys) for details.
***
## Subscription [#subscription]
A recurring billing arrangement linking a tenant to one or more plans. Managed through Stripe. Determines the billing period, quota, and features available to the tenant.
***
## Tenant [#tenant]
The organizational unit in the platform, equivalent to an account or workspace. All API keys, usage, credits, and subscriptions are scoped to a tenant. Users can belong to multiple tenants. See [Account](#account).
***
## Threshold [#threshold]
The percentage of remaining balance (API quota + extra credits) at which Auto Top-Up activates. Configurable between 10% and 30%.
# Introduction (/introduction)
Get started with the Chartquery API in minutes. Make HTTP requests to our endpoints and receive structured JSON responses.
## Quick Start [#quick-start]
### Get your API key [#get-your-api-key]
Sign up on your [dashboard](https://app.chartquery.com) and copy your API key from the **Settings** page.
### Make your first request [#make-your-first-request]
Include your key in the `x-api-key` header and call any endpoint:
```bash
curl "https://api.chartquery.com/v1/usage" \
-H "x-api-key: YOUR_API_KEY"
```
### Handle the response [#handle-the-response]
Every successful request returns a JSON object with structured data. See individual endpoint pages for response schemas and examples.
## Authentication [#authentication]
All API requests must include an `x-api-key` header. You can find your key in your [dashboard → API Keys](https://app.chartquery.com/).
```bash
curl -H "x-api-key: xxxx" https://api.chartquery.com/v1/usage
```
Keep your API key secret. Do not expose it in client-side code or public repositories.
## Status Codes [#status-codes]
Billing applies to successful requests: `200` for synchronous calls, `201` for asynchronous jobs. `404` billing varies by endpoint (check each endpoint page). All other 4xx/5xx responses are free.
| Code | Billed | Status | Action |
| ----- | ------ | ------------------- | -------------------------------------------------------------------------------------------------------- |
| `200` | Yes | Successful API Call | No action required. |
| `201` | Yes | Job Created | No action required. |
| `202` | No | Accepted (Async) | The request was accepted and is being processed. Use the job ID to check the status. |
| `400` | No | Bad Request | Verify your parameters and their types. Check the documentation for more information. |
| `401` | No | Invalid API Key | Check your API key (`x-api-key` header or `x_api_key` query string). |
| `401` | No | Inactive API Key | Activate your API key in the API Keys section of your account settings. |
| `401` | No | Expired API Key | Update your API key or generate a new one. |
| `401` | No | Rate limit exceeded | Back off and retry. Upgrade your plan or raise per-key quotas if this happens often. |
| `402` | No | Payment required | Top up credits, upgrade your plan, enable Auto Top-Up, or settle any open invoices. |
| `403` | No | Forbidden | Verify your permissions. Contact us if you believe this is a mistake. |
| `404` | Varies | Not Found | Billing is endpoint-specific. Check the individual endpoint documentation. |
| `413` | No | Payload Too Large | The uploaded file or request body exceeds the size limit. Check the API documentation for maximum sizes. |
| `500` | No | Internal Error | Retry the action or contact our support team. |
See the [Credits](/credits) page for a full breakdown per endpoint, [API Keys](/api-keys) for key management, and [Best Practices](/best-practices) and [Error Handling](/error-handling) for integration guidance. New to the platform? The [Glossary](/glossary) defines all key terms.
## Endpoints [#endpoints]
Browse every endpoint in the **API reference**, or open one directly:
# Model Context Protocol (/mcp)
The **Model Context Protocol (MCP)** lets AI assistants call **Chartquery** as **tools**: same operations as the REST API, with your **API key**. You can document setup like many teams do: a short README, a sample **`mcp.json`**, and copy-paste steps for your users.
## What you need [#what-you-need]
* A **Chartquery** account ([register](https://app.chartquery.com/register) if needed) and access to the [dashboard](https://app.chartquery.com).
* An **API key** with the **`x-api-key`** header (see [API Keys](/api-keys)).
* **MCP endpoint:** **`https://mcp.chartquery.com/`**
## How it works [#how-it-works]
The server uses **Streamable HTTP** at **`https://mcp.chartquery.com/`**. It is not a normal web page. Each **tool** maps to an API operation; billing and behaviour match the REST API. Use the rest of this documentation for endpoints and parameters.
## Claude Code [#claude-code]
Official docs: [Model Context Protocol (MCP)](https://code.claude.com/docs/en/mcp). Example: **`claude mcp add --transport http chartquery https://mcp.chartquery.com/`** with **`--header`** **`x-api-key: YOUR_API_KEY`**. Use the same URL as in the Cursor section below.
## Cursor [#cursor]
See the [Cursor MCP documentation](https://cursor.com/docs/mcp). In **Settings → MCP**, add an **HTTP** server, or use a project **`mcp.json`** with a **`url`** (ending in `/`) and **`headers`** for your API key.
Use the **MCP endpoint** for **Chartquery** below. Never commit secrets. Prefer environment-specific config or a placeholder like `YOUR_API_KEY`.
```json
{
"mcpServers": {
"chartquery": {
"url": "https://mcp.chartquery.com/",
"headers": {
"x-api-key": "YOUR_API_KEY"
}
}
}
}
```
## Gemini CLI [#gemini-cli]
See [MCP server](https://geminicli.com/docs/tools/mcp-server/) in the Gemini CLI documentation. Point the client at **`https://mcp.chartquery.com/`** and pass your API key (for example via **`x-api-key`**) as the tool docs describe.
## OpenAI Developer Mode [#openai-developer-mode]
See [Developer mode](https://developers.openai.com/api/docs/guides/developer-mode) in the OpenAI API documentation. Wire MCP tools to **`https://mcp.chartquery.com/`** and your **API key** following that guide.
## See also [#see-also]
* [API Keys](/api-keys): create and manage keys
* [Best practices](/best-practices): secure integration
# Status Codes (/status-codes)
Billing applies to successful requests: `200` for synchronous calls, `201` for asynchronous jobs. `404` billing varies by endpoint (check each endpoint page). All other 4xx/5xx responses are free.
| Code | Billed | Status | Action |
| ----- | ------ | ------------------- | -------------------------------------------------------------------------------------------------------- |
| `200` | Yes | Successful API Call | No action required. |
| `201` | Yes | Job Created | No action required. |
| `202` | No | Accepted (Async) | The request was accepted and is being processed. Use the job ID to check the status. |
| `400` | No | Bad Request | Verify your parameters and their types. Check the documentation for more information. |
| `401` | No | Invalid API Key | Check your API key (`x-api-key` header or `x_api_key` query string). |
| `401` | No | Inactive API Key | Activate your API key in the API Keys section of your account settings. |
| `401` | No | Expired API Key | Update your API key or generate a new one. |
| `401` | No | Rate limit exceeded | Back off and retry. Upgrade your plan or raise per-key quotas if this happens often. |
| `402` | No | Payment required | Top up credits, upgrade your plan, enable Auto Top-Up, or settle any open invoices. |
| `403` | No | Forbidden | Verify your permissions. Contact us if you believe this is a mistake. |
| `404` | Varies | Not Found | Billing is endpoint-specific. Check the individual endpoint documentation. |
| `413` | No | Payload Too Large | The uploaded file or request body exceeds the size limit. Check the API documentation for maximum sizes. |
| `500` | No | Internal Error | Retry the action or contact our support team. |
# Timeouts (/timeout)
Most requests respond in a few seconds, but some endpoints can take longer to complete. This page explains our server-side limit and how to make sure your client does not give up before we respond.
## Server-side limit: 60 seconds [#server-side-limit-60-seconds]
All real-time API calls have a hard timeout of **60 seconds** on our side. Typical responses are returned in **2-3 seconds**, occasionally up to **30 seconds**, and the worst case before we abort is **60 seconds**.
If you need to run requests that may take longer than 60 seconds, switch to **async mode** with `is_async=true`. See [Global Parameters](/global-parameters#async-mode).
## Why your request seems to time out earlier [#why-your-request-seems-to-time-out-earlier]
If you observe consistent timeouts at exactly **15s**, **30s**, or any value below 60 seconds, the connection is almost always being closed by **your own infrastructure**, not by our API. Your runtime aborts the HTTP call before we have time to respond.
**Common signs:**
* Errors fire at the exact same duration on every retry (often 10s, 15s, 25s, 30s).
* Our dashboard shows the request as `200` (success) while your client reports a timeout.
* Smaller / cached requests succeed, but heavier ones always fail.
## Platform timeouts to check [#platform-timeouts-to-check]
Below are the default HTTP / function timeouts for the most common platforms. Increase them to at least **60 seconds** to match our server-side limit.
Vercel Serverless and Edge Functions default to **15s** on the Hobby plan (up to **60s**), and **15s** on Pro (up to **300s**, configurable per function).
Set `maxDuration` in your route or function:
```typescript
// app/api/my-route/route.ts (Next.js App Router on Vercel)
export const maxDuration = 60
export async function POST(req: Request) {
// ... call our API
}
```
Or in `vercel.json`:
```json
{
"functions": {
"app/api/**/*.ts": { "maxDuration": 60 }
}
}
```
Reference: [Vercel function duration](https://vercel.com/docs/functions/configuring-functions/duration).
AWS Lambda functions default to **3 seconds** and can be configured up to **15 minutes**.
```bash
# AWS CLI
aws lambda update-function-configuration \
--function-name my-function \
--timeout 60
```
If you call Lambda through API Gateway, also raise the integration timeout (REST APIs default to **29s**, HTTP APIs to **30s**).
Netlify Functions default to **10 seconds** (synchronous) and can be raised to **26 seconds**. For longer requests, use **Background Functions** (up to 15 minutes) or our [async mode](/global-parameters#async-mode).
```toml
# netlify.toml
[functions]
timeout = 26
```
Cloudflare Workers have a **CPU time** limit (10ms / 50ms free, up to 30s paid) but **wall-clock time** is essentially unlimited as long as the connection stays open. Most timeouts come from the upstream `fetch` call.
```typescript
const res = await fetch("https://api.example.com/...", {
signal: AbortSignal.timeout(60_000),
})
```
Make.com (formerly Integromat) has a default HTTP module timeout of **40 seconds**, configurable per call up to **300 seconds**.
In the HTTP module → **Show advanced settings** → set **Timeout** to `60` (or higher).
If your scenario stops on transient HTTP errors, also check our [Soft Fail mode](/global-parameters#soft-fail-mode).
Most HTTP clients have a default request timeout. Make sure you set it to at least **60 seconds**:
```typescript
// Node.js fetch with AbortController
const controller = new AbortController()
const timer = setTimeout(() => controller.abort(), 60_000)
try {
const res = await fetch(url, { signal: controller.signal })
} finally {
clearTimeout(timer)
}
```
```python
# Python requests
import requests
requests.get(url, timeout=60)
```
```bash
# curl
curl --max-time 60 ...
```
## Still seeing timeouts? [#still-seeing-timeouts]
If your client is configured for at least 60 seconds, async mode does not fit your use case, and you still see timeouts, please open a support ticket from your [dashboard](https://app.chartquery.com/) with: the endpoint, a sample `request_id`, the timestamp, and the timeout value you observe. We will investigate.
See [Global Parameters](/global-parameters) for `is_async` and `soft_fail`, [Status Codes](/status-codes) for response codes, and [Best Practices](/best-practices) for retry guidance.
# Usage (/usage)
The Usage endpoint returns your remaining API quota, extra credits, rate limits, and API key details at any time. It does not consume any credits.
Note: the `subscription` object reports your **combined API quota** (subscription allowance + remaining top-ups), not the subscription portion alone. Use the dashboard for a subscription vs top-up split.
This endpoint is free. It never consumes any credits.
## Request [#request]
```bash
curl "https://api.chartquery.com/v1/usage" \
-H "x-api-key: YOUR_API_KEY"
```
## Response Fields [#response-fields]
| Field | Type | Description |
| --------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------- |
| `remaining` | `integer` | Total credits available now (API quota + extra credits) |
| `total_used` | `integer` | Total credits consumed so far (API quota + extra credits; top-up usage persists across billing periods) |
| `renewal_date` | `string` | Date when the subscription renews (ISO 8601) |
| `period.start` | `string` | Start of the current billing period |
| `period.end` | `string` | End of the current billing period |
| `subscription.used` | `integer` | API calls used against your combined API quota |
| `subscription.total` | `integer` | Combined API quota cap (subscription + top-ups) |
| `subscription.remaining` | `integer` | Remaining combined API quota (subscription remainder + unused top-ups) |
| `subscription.percent_used` | `number` | Percentage of API quota consumed |
| `credits.given` | `integer` | Extra credits granted to your account (separate ledger) |
| `credits.consumed` | `integer` | Extra credits consumed |
| `credits.remaining` | `integer` | Extra credits remaining |
| `rate_limit.per_minute` | `integer \| null` | Requests per minute limit (`null` = unlimited) |
| `rate_limit.per_second` | `integer \| null` | Requests per second limit (`null` = unlimited) |
| `account.name` | `string` | Name of the account |
| `account.slug` | `string` | Account identifier slug |
| `api_key.alias` | `string` | Friendly name of the API key |
| `api_key.active` | `boolean` | Whether the key is currently active |
| `api_key.category` | `string` | Key category (e.g. `development`, `production`) |
| `api_key.expires` | `string \| null` | Expiry date of the key (`null` = never expires) |
| `api_key.quotas` | `object` | Custom per-key quotas: `total`, `daily`, `weekly`, `monthly` |
## Example Response [#example-response]
```json
{
"remaining": 450,
"total_used": 1550,
"renewal_date": "2026-04-25",
"period": {
"start": "2026-03-25",
"end": "2026-04-25"
},
"subscription": {
"used": 1550,
"total": 2000,
"remaining": 450,
"percent_used": 77
},
"credits": {
"given": 0,
"consumed": 0,
"remaining": 0,
"percent_used": 0
},
"rate_limit": {
"per_minute": null,
"per_second": null
},
"account": {
"name": "Acme Corp",
"slug": "acme-corp"
},
"api_key": {
"alias": "production",
"active": true,
"category": "production",
"expires": null,
"quotas": {
"total": null,
"daily": null,
"weekly": null,
"monthly": null
}
}
}
```
# Barcode (/barcode)
**GET** `https://api.chartquery.com/v1/barcode`
Generate a barcode image via GET. Output: SVG (default) or PNG. Supports 25+ formats: EAN-13, Code 128, ITF-14, GS1-128, postal codes and more.
**Credit cost:** 3 credits per call
## Parameters
| Name | In | Type | Required | Description |
|------|----|------|:--------:|-------------|
| `data` | query | `string` | Yes | The data to encode in the barcode. Examples by type: **EAN-13** (retail): `4006381333931` **EAN-8** (small pack): `73513535` **UPC-A** (North America): `012345678905` **Code 128** (general): `HELLO-WORLD-2026` or `INV-2026-00456` **Code 39** (uppercase): `CODE39-DEMO` or `SHELF-A12` **ITF-14** (carton): `00012345678905` **GS1-128** (with AIs): `(01)12345678901234(17)260101` **Codabar** (library): `A1234567890B` **POSTNET** (postal): `902100123` |
| `type` | query | `string` (`code128`, `ean13`, `ean8`, `upca`, `upce`, `code39`, `itf`, `itf14`, `codabar`, `gs1-128`, `postnet`, `planet`, `plessey`) | No | Barcode format. Default: `code128`. **Retail:** `ean13`, `ean8`, `ean5`, `ean2`, `upca`, `upce` **General:** `code128`, `code39`, `code39ext`, `code93`, `code93ext` **Logistics:** `itf`, `itf14`, `gs1-128`, `gs1-databar`, `gs1-databar-limited`, `gs1-databar-expanded` **Other:** `codabar`, `msi`, `pharmacode`, `code11`, `plessey` **Postal:** `postnet`, `planet`, `identcode`, `leitcode` |
| `height` | query | `number` | No | Bar height in pixels. Default: 80. Typical values: 50 (compact), 80 (standard), 100–120 (tall labels). Example: ?height=100 |
| `color` | query | `string` | No | Bar color as a CSS color string. Default: #000. Examples: ?color=%231e293b (dark slate), ?color=%230f172a (near black), ?color=%237c3aed (purple), ?color=%23dc2626 (red). Use %23 to URL-encode the # character. |
| `show_text` | query | `boolean` | No | Show human-readable text below the bars. Example: ?show_text=true. Combine with font_size and text_align for print labels. |
| `text_position` | query | `string` (`bottom`, `top`) | No | Position of the human-readable text label. Default: bottom. Example: ?text_position=top |
| `text_align` | query | `string` (`center`, `left`, `right`) | No | Horizontal alignment of the text label. Default: center. Example: ?text_align=left |
| `font_size` | query | `number` | No | Font size of the text label in pixels. Default: 14. Example: ?font_size=12 |
| `font_family` | query | `string` | No | Font family of the text label. Default: monospace. Examples: ?font_family=monospace, ?font_family=sans-serif, ?font_family=Arial |
| `bar_width` | query | `number` | No | Width multiplier per module (bar). Default: 2. Increase for wider, more scannable barcodes. Example: ?bar_width=3 |
| `bar_gap` | query | `number` | No | Extra horizontal spacing between bars in pixels. Default: 0. Example: ?bar_gap=1 |
| `background` | query | `string` | No | Background fill color. Default: #fff. Use transparent for no background. Example: ?background=%23f8fafc |
| `margin` | query | `number` | No | Uniform margin around the barcode in pixels. Default: 10. Overridden per side by margin_top/bottom/left/right. Example: ?margin=6 |
| `margin_top` | query | `number` | No | Top margin in pixels (overrides margin). Example: ?margin_top=4 |
| `margin_bottom` | query | `number` | No | Bottom margin in pixels (overrides margin). Example: ?margin_bottom=4 |
| `margin_left` | query | `number` | No | Left margin in pixels (overrides margin). Example: ?margin_left=8 |
| `margin_right` | query | `number` | No | Right margin in pixels (overrides margin). Example: ?margin_right=8 |
| `rotation` | query | `number` (`0`, `90`, `180`, `270`) | No | Rotate the barcode by 0, 90, 180 or 270 degrees. Default: 0. Use 90 or 270 for vertical label orientation. Example: ?rotation=90 |
| `bearer_bars` | query | `boolean` | No | Add horizontal bearer bars above and below the barcode. Required for ITF-14. Default: false. Example: ?bearer_bars=true |
| `unit` | query | `string` (`px`, `mm`, `in`, `cm`) | No | Measurement unit for dimensions. Default: px. Use mm, in or cm for print-ready output. Example: ?unit=mm |
| `aria_label` | query | `string` | No | Accessible label added as aria-label on the SVG element. Improves screen reader support. Example: ?aria_label=EAN-13+barcode+for+product+4006381333931 |
| `title` | query | `string` | No | SVG element for tooltip and accessibility. Example: ?title=Product+Barcode |
| `desc` | query | `string` | No | SVG <desc> element for extended accessibility description. Example: ?desc=EAN-13+encoding+GTIN+for+Nivea+cream+75ml |
| `format` | query | `string` (`svg`, `png`) | No | Output format. Default: svg. Use png to get a raster image. SVG is lossless and scalable; PNG is pixel-based and suitable for email, PDF or messaging. Example: ?format=png |
| `share` | query | `boolean` (`false`, `true`) | No | Set share=true to persist the config and receive JSON instead of an image: { id, render_url, view_url, embed_url, expires_in }. Free plan: 3-day expiry with watermark. Paid plan: 6-month expiry, no branding. |
## Responses
### 200 Successful response
### 400 Bad Request — missing or invalid parameters.
```json
{
"error": "Bad Request"
}
```
### 500 Internal Server Error — something went wrong on our side.
```json
{
"error": "Internal Error"
}
```
# Chart AI (/chart-ai)
**GET** `https://api.chartquery.com/v1/chart/ai`
Describe a chart in plain English via GET and get a rendered image back. Powered by AI.
**Credit cost:** 10 credits per call
## Authentication
Pass your API key as a header:
```
x-api-key: YOUR_API_KEY
```
## Parameters
| Name | In | Type | Required | Description |
|------|----|------|:--------:|-------------|
| `prompt` | query | `string` | Yes | Describe your chart in plain English (max 1000 chars). Be specific: mention chart type, data topic, colors, style. |
| `raw_data` | query | `string` | No | Raw data for the chart. URL-encoded string, CSV, or JSON. AI will parse and structure it. Examples: - String: `Jan: 12400, Feb: 18900, Mar: 15200` - JSON array: `[{"month":"Jan","a":120,"b":85},{"month":"Feb","a":145,"b":102}]` - JSON object: `{"Organic":38,"Paid":24,"Direct":18}` Limit: 10 000 characters / 500 items. Need more? Open a support ticket. |
| `title` | query | `string` | No | Override the chart title generated by AI. |
| `subtitle` | query | `string` | No | Override the chart subtitle. |
| `legend` | query | `string` (`top`, `bottom`, `left`, `right`, `chartArea`, `false`) | No | Legend position or visibility. Use "false" to hide. |
| `format` | query | `string` (`png`, `svg`) | No | Output format. Default: "png". |
| `width` | query | `number` | No | Image width in pixels (50–4000). Default: 1200. |
| `height` | query | `number` | No | Image height in pixels (50–4000). Default: 600. |
| `background` | query | `string` | No | Background color as a hex value. Default: #ffffff. |
| `device_pixel_ratio` | query | `number` | No | Device pixel ratio for the rendered image. Default: 1. |
| `share` | query | `boolean` (`false`, `true`) | No | Set share=true to persist the config and receive JSON instead of an image: { id, render_url, view_url, embed_url, expires_in }. Free plan: 3-day expiry with watermark. Paid plan: 6-month expiry, no branding. |
## Responses
### 200 Successful response
```json
{
"type": "string"
}
```
### 400 Bad Request — missing or invalid parameters.
```json
{
"error": "Bad Request"
}
```
### 401 Unauthorized — the API key is missing, invalid, inactive, or expired.
```json
{
"error": "Invalid API Key"
}
```
### 402 Payment Required — your subscription or credit balance is insufficient.
```json
{
"error": "Payment required"
}
```
### 429 Too Many Requests — you exceeded your rate limit quota.
```json
{
"error": "Rate limit exceeded for the API key: quota monthly"
}
```
### 500 Internal Server Error — something went wrong on our side.
```json
{
"error": "Internal Error"
}
```
# Chart Render (/chart-render-id)
**GET** `https://api.chartquery.com/v1/chart/render/{id}`
Render a previously saved chart by ID. Public, no API key required. Supports URL overrides for templates (?data1=, ?labels=, ?title=…).
## Parameters
| Name | In | Type | Required | Description |
|------|----|------|:--------:|-------------|
| `title` | query | `string` | No | Override the chart title. |
| `labels` | query | `string` | No | Override X-axis labels. Comma-separated. |
| `data1` | query | `string` | No | Override first dataset values. Comma-separated numbers. Use data2, data3… for additional datasets. |
| `width` | query | `string` | No | Override output width in pixels (50–4000). |
| `height` | query | `string` | No | Override output height in pixels (50–4000). |
| `format` | query | `string` (`png`, `svg`) | No | Override output format. |
| `id` | path | `string` | Yes | The chart ID returned in the X-Chart-Render-URL header when saving a chart. Format: cq-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. |
## Responses
### 200 Successful response
### 400 Bad Request — missing or invalid parameters.
```json
{
"error": "Bad Request"
}
```
### 500 Internal Server Error — something went wrong on our side.
```json
{
"error": "Internal Error"
}
```
# Chart View (/chart-view-id)
**GET** `https://api.chartquery.com/v1/chart/view/{id}`
View a previously saved chart as an interactive HTML page. Public, no API key required. Iframe-embeddable.
## Parameters
| Name | In | Type | Required | Description |
|------|----|------|:--------:|-------------|
| `share` | query | `boolean` (`false`, `true`) | No | Set share=true to persist the config and receive JSON instead of an image: { id, render_url, view_url, embed_url, expires_in }. Free plan: 3-day expiry with watermark. Paid plan: 6-month expiry, no branding. |
| `id` | path | `string` | Yes | The chart ID returned in the X-Chart-View-URL header when saving a chart. Format: cq-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. |
## Responses
### 200 Successful response
```json
{
"type": "string"
}
```
### 400 Bad Request — missing or invalid parameters.
```json
{
"error": "Bad Request"
}
```
### 500 Internal Server Error — something went wrong on our side.
```json
{
"error": "Internal Error"
}
```
# Chart (/chart)
**GET** `https://api.chartquery.com/v1/chart`
Generate a chart image (PNG or SVG) via GET. Pass the full chart config as URL-encoded JSON in the query parameter.
**Credit cost:** 5 credits per call
## Parameters
| Name | In | Type | Required | Description |
|------|----|------|:--------:|-------------|
| `query` | query | `string` | Yes | Full chart config as URL-encoded JSON. Pass `?version=` or `?v=` separately to pin the chart version. **Bar chart** (copy & paste as ?query=): `{"type":"bar","title":"Monthly Sales","legend":"bottom","width":1200,"height":600,"device_pixel_ratio":1,"data":{"labels":["Jan","Feb","Mar","Apr","May","Jun"],"datasets":[{"label":"2025","data":[42,58,37,65,49,72],"backgroundColor":"rgba(99,102,241,0.85)"},{"label":"2026","data":[51,67,44,71,58,85],"backgroundColor":"rgba(249,115,22,0.85)"}]},"scales":{"y":{"beginAtZero":true}}}` **Line chart** (dual Y-axis): `{"type":"line","title":"Revenue vs Conversion","legend":"top","width":1200,"height":600,"device_pixel_ratio":1,"data":{"labels":["Jan","Feb","Mar","Apr","May","Jun"],"datasets":[{"label":"Revenue (€)","data":[12000,18500,15200,21800,9300,17400],"borderColor":"#6366f1","tension":0.4,"fill":false,"yAxisID":"y"},{"label":"Conversion (%)","data":[3.2,4.1,2.8,5.0,1.9,3.7],"borderColor":"#f97316","tension":0.4,"fill":false,"yAxisID":"y2"}]},"scales":{"y":{"position":"left"},"y2":{"position":"right","grid":{"display":false}}}}` **Stacked area chart**: `{"type":"area","title":"API Usage by Brand","legend":"top","width":1200,"height":600,"device_pixel_ratio":1,"data":{"labels":["Jan","Feb","Mar","Apr","May","Jun"],"datasets":[{"label":"CaptureKit","data":[12400,18900,14300,21500,9800,16200],"borderColor":"#6366f1","backgroundColor":"rgba(99,102,241,0.35)","tension":0.4,"stack":"total"},{"label":"ChartQuery","data":[3200,6900,11500,8300,14700,9800],"borderColor":"#22c55e","backgroundColor":"rgba(34,197,94,0.35)","tension":0.4,"stack":"total"}]},"scales":{"y":{"stacked":true,"beginAtZero":true}}}` **Doughnut chart**: `{"type":"doughnut","title":"Traffic Sources","legend":"right","width":800,"height":500,"device_pixel_ratio":1,"data":{"labels":["Organic","Paid","Direct","Referral","Social"],"datasets":[{"data":[38,24,18,12,8],"backgroundColor":["#6366f1","#f97316","#22c55e","#ef4444","#eab308"],"borderWidth":2,"borderColor":"#ffffff"}]}}` **Radar chart**: `{"type":"radar","title":"Performance v1 vs v2","legend":"top","width":800,"height":700,"device_pixel_ratio":1,"data":{"labels":["Speed","Reliability","Security","UX","Scalability"],"datasets":[{"label":"v1","data":[65,70,80,60,75],"borderColor":"#6366f1","backgroundColor":"rgba(99,102,241,0.25)"},{"label":"v2","data":[88,92,90,85,95],"borderColor":"#f97316","backgroundColor":"rgba(249,115,22,0.25)"}]}}` **SVG output** (add `"format":"svg"` to any example above for infinitely scalable output). |
| `version` | query | `string` | No | Chart.js version to use. Alias: ?v=. Only v4.x is supported. Defaults to the installed version (4.5.1). Example: "4", "4.5", "4.5.1". The installed version is always returned in the X-ChartJS-Version response header. |
| `share` | query | `boolean` | No | Set share: true to persist the chart and receive a JSON response with render_url and view_url instead of the image. render_url is a public direct image URL (embeddable in emails, iframes, Markdown). view_url is a shareable interactive HTML page. Free plan: expires after 3 days with watermark. Paid plan: expires after 6 months, no branding. |
## Responses
### 200 Successful response
### 400 Bad Request — missing or invalid parameters.
```json
{
"error": "Bad Request"
}
```
### 500 Internal Server Error — something went wrong on our side.
```json
{
"error": "Internal Error"
}
```
# Diagram AI (/diagram-ai)
**GET** `https://api.chartquery.com/v1/diagram/ai`
Describe a diagram in plain English via GET and get a rendered image back. Powered by AI.
**Credit cost:** 10 credits per call
## Authentication
Pass your API key as a header:
```
x-api-key: YOUR_API_KEY
```
## Parameters
| Name | In | Type | Required | Description |
|------|----|------|:--------:|-------------|
| `prompt` | query | `string` | Yes | Describe your diagram in plain English (max 1000 chars). Be specific: mention the diagram type, key entities, and relationships. |
| `diagram_type` | query | `string` (`mermaid`, `d2`, `plantuml`, `graphviz`) | No | Preferred diagram language. AI chooses if omitted. Examples: "mermaid", "d2", "plantuml", "graphviz". |
| `output_format` | query | `string` (`svg`, `png`, `jpeg`, `pdf`) | No | Output format. Default: "svg". |
| `share` | query | `boolean` (`false`, `true`) | No | Set share=true to persist the config and receive JSON instead of an image: { id, render_url, view_url, embed_url, expires_in }. Free plan: 3-day expiry. Paid plan: 6-month expiry. |
## Responses
### 200 Successful response
```json
{
"type": "string"
}
```
### 400 Bad Request — missing or invalid parameters.
```json
{
"error": "Bad Request"
}
```
### 401 Unauthorized — the API key is missing, invalid, inactive, or expired.
```json
{
"error": "Invalid API Key"
}
```
### 402 Payment Required — your subscription or credit balance is insufficient.
```json
{
"error": "Payment required"
}
```
### 429 Too Many Requests — you exceeded your rate limit quota.
```json
{
"error": "Rate limit exceeded for the API key: quota monthly"
}
```
### 500 Internal Server Error — something went wrong on our side.
```json
{
"error": "Internal Error"
}
```
# Diagram Render (/diagram-render-id)
**GET** `https://api.chartquery.com/v1/diagram/render/{id}`
Render a previously saved diagram by ID. Public, no API key required. Supports ?format= and ?query= overrides.
## Parameters
| Name | In | Type | Required | Description |
|------|----|------|:--------:|-------------|
| `format` | query | `string` (`svg`, `png`, `jpeg`, `pdf`) | No | Override output format. |
| `query` | query | `string` | No | Override the diagram source code (URL-encoded). |
| `share` | query | `boolean` (`false`, `true`) | No | Set share=true to persist the config and receive JSON instead of an image: { id, render_url, view_url, embed_url, expires_in }. Free plan: 3-day expiry with watermark. Paid plan: 6-month expiry, no branding. |
| `id` | path | `string` | Yes | The diagram ID returned in the X-Diagram-Render-URL header when saving a diagram. Format: cq-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. |
## Responses
### 200 Successful response
### 400 Bad Request — missing or invalid parameters.
```json
{
"error": "Bad Request"
}
```
### 500 Internal Server Error — something went wrong on our side.
```json
{
"error": "Internal Error"
}
```
# Diagram View (/diagram-view-id)
**GET** `https://api.chartquery.com/v1/diagram/view/{id}`
View a previously saved diagram as an HTML page. Public, no API key required. Iframe-embeddable with inline SVG rendering.
## Parameters
| Name | In | Type | Required | Description |
|------|----|------|:--------:|-------------|
| `share` | query | `boolean` (`false`, `true`) | No | Set share=true to persist the config and receive JSON instead of an image: { id, render_url, view_url, embed_url, expires_in }. Free plan: 3-day expiry with watermark. Paid plan: 6-month expiry, no branding. |
| `id` | path | `string` | Yes | The diagram ID returned in the X-Diagram-View-URL header when saving a diagram. Format: cq-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. |
## Responses
### 200 Successful response
```json
{
"type": "string"
}
```
### 400 Bad Request — missing or invalid parameters.
```json
{
"error": "Bad Request"
}
```
### 500 Internal Server Error — something went wrong on our side.
```json
{
"error": "Internal Error"
}
```
# Diagram (/diagram)
**GET** `https://api.chartquery.com/v1/diagram`
Generate a diagram (SVG, PNG…) via GET using ?type=mermaid&query=...&format=svg.
**Credit cost:** 5 credits per call
## Parameters
| Name | In | Type | Required | Description |
|------|----|------|:--------:|-------------|
| `type` | query | `string` (`mermaid`, `graphviz`, `plantuml`, `d2`, `svgbob`, `nomnoml`, `blockdiag`, `seqdiag`, `actdiag`, `nwdiag`, `bpmn`, `erd`, `excalidraw`, `ditaa`, `vega`, `vegalite`, `wavedrom`, `wireviz`, `c4plantuml`, `structurizr`, `tikz`, `pikchr`, `umlet`, `symbolator`, `packetdiag`, `rackdiag`, `bytefield`, `dbml`) | Yes | Diagram language. |
| `query` | query | `string` | Yes | Diagram source code (URL-encoded). **mermaid**: flowchart: `graph TD\n A[Start] --> B{OK?}\n B -->\|yes\| C[End]\n B -->\|no\| D[Error]` **mermaid**: sequence: `sequenceDiagram\n Client->>API: GET /v1/diagram\n API-->>Client: 200 SVG` **mermaid**: ER: `erDiagram\n USER \|\|--o{ ORDER : places\n ORDER \|\|--\|{ ITEM : contains` **graphviz**: `digraph G { rankdir=LR; A -> B -> C }` **plantuml**: `@startuml\nA -> B: request\nB --> A: response\n@enduml` **d2**: `Client -> API: POST /v1/diagram\nAPI -> SVG` **svgbob**: `+-------+ +-------+\n\| Box A \|-->\| Box B \|\n+-------+ +-------+` **nomnoml**: `[Client] -> [API]\n[API] -> [Handler]` |
| `format` | query | `string` (`svg`, `png`, `jpeg`, `pdf`) | No | Output format. Default: "svg". |
| `share` | query | `boolean` | No | Set share: true to persist the diagram and receive a JSON response with render_url and view_url instead of the image. render_url is a public direct image URL (no auth required, supports ?format= override). view_url is a shareable HTML page embeddable as an iframe. Free plan: expires after 3 days. Paid plan: expires after 6 months. |
## Responses
### 200 Successful response
### 400 Bad Request — missing or invalid parameters.
```json
{
"error": "Bad Request"
}
```
### 500 Internal Server Error — something went wrong on our side.
```json
{
"error": "Internal Error"
}
```
# Label Compile (/label-compile)
**POST** `https://api.chartquery.com/v1/label/compile`
Compile a label definition into printer commands. Returns raw TSC, ZPL, EPL, ESC/POS or other language output ready to send to a thermal printer.
**Credit cost:** 3 credits per call
## Responses
### 200 Successful response
```json
{
"type": "string"
}
```
### 400 Bad Request — missing or invalid parameters.
```json
{
"error": "Bad Request"
}
```
### 500 Internal Server Error — something went wrong on our side.
```json
{
"error": "Internal Error"
}
```
# Label Convert (/label-convert)
**POST** `https://api.chartquery.com/v1/label/convert`
Cross-compile printer commands between languages. 7 source x 9 target = 63 conversion paths. TSC to ZPL, ZPL to ESC/POS, EPL to CPCL and more.
**Credit cost:** 5 credits per call
## Responses
### 200 Successful response
```json
{
"type": "object",
"properties": {
"to": {
"type": "string"
},
"from": {
"type": "string"
},
"output": {
"type": "string"
},
"warnings": {
"type": "array",
"items": {}
},
"width_dots": {
"type": "integer"
},
"height_dots": {
"type": "integer"
},
"elements_count": {
"type": "integer"
},
"output_encoding": {
"type": "string"
}
}
}
```
### 400 Bad Request — missing or invalid parameters.
```json
{
"error": "Bad Request"
}
```
### 500 Internal Server Error — something went wrong on our side.
```json
{
"error": "Internal Error"
}
```
# Label Parse (/label-parse)
**POST** `https://api.chartquery.com/v1/label/parse`
Parse printer commands back to structured data. Reverse-engineer existing label code into elements, dimensions and metadata.
**Credit cost:** 1 credit per call
## Responses
### 200 Successful response
```json
{
"type": "object",
"properties": {
"dpi": {
"type": "integer"
},
"commands": {
"type": "array",
"items": {
"type": "object",
"properties": {
"cmd": {
"type": "string"
},
"unit": {
"type": "string"
},
"widthMM": {
"type": "integer"
},
"heightMM": {
"type": "integer"
}
}
}
},
"elements": {
"type": "array",
"items": {
"type": "object",
"properties": {
"x": {
"type": "integer"
},
"y": {
"type": "integer"
},
"font": {
"type": "string"
},
"size": {
"type": "integer"
},
"type": {
"type": "string"
},
"content": {
"type": "string"
},
"rotation": {
"type": "integer"
}
}
}
},
"warnings": {
"type": "array",
"items": {}
},
"widthDots": {
"type": "integer"
},
"heightDots": {
"type": "integer"
}
}
}
```
### 400 Bad Request — missing or invalid parameters.
```json
{
"error": "Bad Request"
}
```
### 500 Internal Server Error — something went wrong on our side.
```json
{
"error": "Internal Error"
}
```
# Label Render (/label-render-id)
**GET** `https://api.chartquery.com/v1/label/render/{id}`
Render a previously saved label by ID. Public, no API key required. Supports ?format= override.
## Parameters
| Name | In | Type | Required | Description |
|------|----|------|:--------:|-------------|
| `id` | query | `string` | Yes | Label ID from the share response. |
| `format` | query | `string` (`svg`, `png`) | No | Override output format. |
| `id` | path | `string` | Yes | |
## Responses
### 200 Successful response
### 400 Bad Request — missing or invalid parameters.
```json
{
"error": "Bad Request"
}
```
### 500 Internal Server Error — something went wrong on our side.
```json
{
"error": "Internal Error"
}
```
# Label Validate (/label-validate)
**POST** `https://api.chartquery.com/v1/label/validate`
Validate printer commands for errors, warnings and best practices. Checks parameter ranges, command order and structure.
**Credit cost:** 1 credit per call
## Responses
### 200 Successful response
```json
{
"type": "object",
"properties": {
"infos": {
"type": "integer"
},
"valid": {
"type": "boolean"
},
"errors": {
"type": "integer"
},
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"level": {
"type": "string"
},
"command": {
"type": "string"
},
"message": {
"type": "string"
}
}
}
},
"warnings": {
"type": "integer"
}
}
}
```
### 400 Bad Request — missing or invalid parameters.
```json
{
"error": "Bad Request"
}
```
### 500 Internal Server Error — something went wrong on our side.
```json
{
"error": "Internal Error"
}
```
# Label View (/label-view-id)
**GET** `https://api.chartquery.com/v1/label/view/{id}`
View a previously saved label as an HTML page. Public, no API key required. Iframe-embeddable with inline SVG rendering.
## Parameters
| Name | In | Type | Required | Description |
|------|----|------|:--------:|-------------|
| `id` | query | `string` | Yes | Label ID from the share response. |
| `id` | path | `string` | Yes | |
## Responses
### 200 Successful response
```json
{
"type": "string"
}
```
### 400 Bad Request — missing or invalid parameters.
```json
{
"error": "Bad Request"
}
```
### 500 Internal Server Error — something went wrong on our side.
```json
{
"error": "Internal Error"
}
```
# Label Preview (/label)
**GET** `https://api.chartquery.com/v1/label`
Generate a thermal label preview via GET. Output: SVG (default) or PNG. Supports 9 printer languages: TSC, ZPL, EPL, ESC/POS, CPCL, DPL, SBPL, Star PRNT, IPL.
**Credit cost:** 3 credits per call
## Parameters
| Name | In | Type | Required | Description |
|------|----|------|:--------:|-------------|
| `format` | query | `string` (`svg`, `png`) | No | Output format. Default: svg. Use png to get a raster image. |
| `share` | query | `boolean` (`false`, `true`) | No | Set share=true to persist the config and receive JSON instead of an image. |
| `query` | query | `string` | Yes | Full label config as URL-encoded JSON. |
## Responses
### 200 Successful response
### 400 Bad Request — missing or invalid parameters.
```json
{
"error": "Bad Request"
}
```
### 500 Internal Server Error — something went wrong on our side.
```json
{
"error": "Internal Error"
}
```
# QR Code (/qrcode)
**GET** `https://api.chartquery.com/v1/qrcode`
Generate a styled QR code via GET. Output: SVG (default) or PNG. Supports dot styles, gradients, custom corners and all QR versions.
**Credit cost:** 3 credits per call
## Parameters
| Name | In | Type | Required | Description |
|------|----|------|:--------:|-------------|
| `data` | query | `string` | Yes | Data to encode in the QR code. Examples: **URL:** `https://chartquery.com` **Email:** `mailto:hello@chartquery.com` **Phone:** `tel:+1234567890` **SMS:** `SMSTO:+1234567890:Hello!` **WiFi:** `WIFI:T:WPA;S:MyNetwork;P:secret123;;` **Geo:** `geo:48.8566,2.3522` **Plain text:** `Hello from ChartQuery!` **vCard:** `BEGIN:VCARD VERSION:3.0 FN:John Doe EMAIL:john@example.com END:VCARD` |
| `size` | query | `number` | No | Output size in pixels (width = height). Default: 200. Examples: ?size=200 (thumbnail), ?size=300 (standard), ?size=400 (large), ?size=600 (poster). For print, use the unit param with mm/cm instead. |
| `ec_level` | query | `string` (`L`, `M`, `Q`, `H`) | No | Error correction level. Default: M. Higher levels allow more damage/obscuring before the code becomes unreadable. - **L** (7%): smallest size, minimal redundancy, best for clean environments - **M** (15%): balanced, good for most use cases - **Q** (25%), for outdoor or rough surfaces - **H** (30%): required when adding a logo or image overlay Example: ?ec_level=H |
| `dot_type` | query | `string` (`square`, `rounded`, `dots`, `diamond`, `classy`, `classy-rounded`, `extra-rounded`, `vertical-line`, `horizontal-line`, `small-square`, `tiny-square`) | No | Module (dot) shape. Default: `square`. Controls the visual style of each QR code module. - `square`: classic, maximum compatibility - `rounded`: softer edges, clean modern look - `dots`: fully circular modules, artistic - `diamond`: angular style - `classy`: elegant angular corners - `classy-rounded`: classy with rounded tips - `extra-rounded`: large pill-shaped modules - `small-square` / `tiny-square`: spaced square modules - `vertical-line` / `horizontal-line`: striped effect Example: ?dot_type=rounded |
| `color` | query | `string` | No | Module color as CSS hex. Default: #000. Examples: ?color=%236366f1 (indigo), ?color=%23dc2626 (red), ?color=%23059669 (green), ?color=%230891b2 (teal). Use %23 to URL-encode #. For gradient objects, use POST instead. |
| `shape` | query | `string` (`square`, `circle`) | No | Overall QR code shape. Default: square. Use circle to clip the entire QR into a circle: great for profile/avatar-style codes. Example: ?shape=circle&dot_type=dots |
| `dot_size` | query | `number` | No | Module size ratio between 0.1 and 1. Default: 1 (full). Values below 1 add spacing between modules for a lighter look. Example: ?dot_size=0.85 |
| `background` | query | `string` | No | Background color. Default: #fff. Set to transparent for no background. Example: ?background=%230f172a for dark background. Use %23 to encode #. |
| `margin` | query | `number` | No | Quiet zone width in modules around the QR code. Default: 4. Minimum recommended by the QR standard: 4. Example: ?margin=2 (compact) or ?margin=6 (extra padding). |
| `version` | query | `number` | No | QR version from 1 to 40 (determines grid size and data capacity). Leave unset for auto-selection based on data length and ec_level. Example: ?version=5 |
| `mode` | query | `string` (`auto`, `numeric`, `alphanumeric`, `byte`) | No | Encoding mode. Default: auto (best mode selected for the data). Use numeric for digits-only, alphanumeric for uppercase + digits, byte for arbitrary text/UTF-8. Example: ?mode=numeric |
| `mask` | query | `number` | No | Mask pattern from 0 to 7. Default: auto (best mask selected to minimize visual patterns). Only set manually if you need a deterministic output. Example: ?mask=3 |
| `unit` | query | `string` (`px`, `mm`, `in`, `cm`) | No | Measurement unit for the size param. Default: px. Use mm, in or cm with the size param for print-ready output. Example: ?size=50&unit=mm |
| `xml_declaration` | query | `boolean` | No | Prepend an XML declaration (<?xml version="1.0" encoding="UTF-8"?>) to the SVG output. Useful when the SVG will be used as a standalone XML file. Default: false. Example: ?xml_declaration=true |
| `aria_label` | query | `string` | No | Accessible label added as aria-label on the SVG element. Example: ?aria_label=QR+code+linking+to+chartquery.com |
| `title` | query | `string` | No | SVG <title> element shown as a browser tooltip and used by screen readers. Example: ?title=ChartQuery+Website |
| `desc` | query | `string` | No | SVG <desc> element for extended accessibility description. Example: ?desc=Scan+to+visit+https://chartquery.com |
| `format` | query | `string` (`svg`, `png`) | No | Output format. Default: svg. Use png to get a raster image. SVG is lossless and scalable; PNG is pixel-based and suitable for email, PDF or messaging. Example: ?format=png |
| `share` | query | `boolean` (`false`, `true`) | No | Set share=true to persist the config and receive JSON instead of an image: { id, render_url, view_url, embed_url, expires_in }. Free plan: 3-day expiry with watermark. Paid plan: 6-month expiry, no branding. |
## Responses
### 200 Successful response
### 400 Bad Request — missing or invalid parameters.
```json
{
"error": "Bad Request"
}
```
### 500 Internal Server Error — something went wrong on our side.
```json
{
"error": "Internal Error"
}
```
# Stats (/stats)
**GET** `https://api.chartquery.com/v1/stats`
Infrastructure health for an engine or endpoint over the last hour. Not scoped to your account or tenant. Enabled per account: HTTP 403 means contact support to activate it.
## Authentication
Pass your API key as a header:
```
x-api-key: YOUR_API_KEY
```
## Parameters
| Name | In | Type | Required | Description |
|------|----|------|:--------:|-------------|
| `engine` | query | `string` | No | API family to check, for example `chart`. Provide at least `engine` or `path`. |
| `path` | query | `string` | No | Specific endpoint to check, for example `/v1/chart`. If you also pass `engine`, use an endpoint from that API. |
## Responses
### 200 Successful response
```json
{
"type": "object",
"properties": {
"path": {
"nullable": true
},
"engine": {
"type": "string"
},
"health": {
"type": "string"
},
"window": {
"type": "string"
},
"success_rate": {
"type": "number"
},
"avg_response_time_ms": {
"type": "integer"
}
}
}
```
### 400 Bad Request — missing or invalid parameters.
```json
{
"error": "Bad Request"
}
```
### 401 Unauthorized — the API key is missing, invalid, inactive, or expired.
```json
{
"error": "Invalid API Key"
}
```
### 402 Payment Required — your subscription or credit balance is insufficient.
```json
{
"error": "Payment required"
}
```
### 429 Too Many Requests — you exceeded your rate limit quota.
```json
{
"error": "Rate limit exceeded for the API key: quota monthly"
}
```
### 500 Internal Server Error — something went wrong on our side.
```json
{
"error": "Internal Error"
}
```
# Help center (/)
Welcome to the Chartquery help center. This guide covers everything you do in the dashboard: creating an account, issuing API keys, tracking credits, reading request logs, and inviting your team. Looking for endpoint parameters instead? Head to the **API reference**.
<DocFigure caption="The Chartquery dashboard: usage at a glance, API keys, and billing in one place.">
<HelpCenterOverviewIllustration />
</DocFigure>
## Start here [#start-here]
* **New to Chartquery?** Follow the [quick start](/getting-started/quick-start) to go from signup to your first API response.
* **Ready to integrate?** Create a key in [API keys](/keys/create-and-manage), then read the [Developer guide](/introduction).
* **Watching your spend?** [Credits](/billing/credits) explains how balances work and when calls are billed.
## How the documentation is organised [#how-the-documentation-is-organised]
| Section | What you will find |
| ------------------- | ------------------------------------------------------------------------ |
| **User guide** | Everything you do in the dashboard, with an illustration of each screen. |
| **Developer guide** | Authentication, global parameters, error handling, and playbooks. |
| **API reference** | OpenAPI pages for every endpoint: parameters, examples, and responses. |
## A typical path [#a-typical-path]
* Create an account and land on the **Library**.
* Issue an **API key**, store the secret, and call `/v1/usage` to verify authentication.
* Open an endpoint in the Library, try it in the playground, then wire the same call into your backend.
* Watch spend in **Analytics**, debug individual calls in **API Logs**, and top up from **Settings → Subscription** when the balance drops.
<Callout type="info">
Every page has a **Copy markdown** button at the top. Paste it into an AI assistant to get help tailored to your integration.
</Callout>
## Related [#related]
<Cards>
<Card title="Quick start" href="/getting-started/quick-start" />
<Card title="Create and manage API keys" href="/keys/create-and-manage" />
<Card title="Plans and pricing" href="/billing/plans-and-pricing" />
</Cards>
# Collect Google Images (/playbooks/autom-google-images)
## Overview [#overview]
This playbook shows how to collect image URLs, titles, and dimensions from Google Images for a given query. Each result includes the direct image URL, the page it was found on, its source domain, and pixel dimensions.
## Prerequisites [#prerequisites]
* An Autom API key — get one at [app.autom.dev](https://app.autom.dev)
* Install dependencies for your language:
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```bash
pip install requests
```
</Tab>
<Tab value="TypeScript">
No extra dependencies — uses the native `fetch` API (Node 18+).
</Tab>
<Tab value="PHP">
`curl` extension enabled (on by default in most PHP installs).
</Tab>
<Tab value="Go">
No extra dependencies — uses `net/http` (Go 1.18+).
</Tab>
<Tab value="Java">
No extra dependencies — uses `java.net.http` (Java 11+).
</Tab>
<Tab value="C#">
No extra dependencies — uses `System.Net.Http` (.NET 6+).
</Tab>
<Tab value="Rust">
```toml
# Cargo.toml
[dependencies]
reqwest = { version = "0.12", features = ["json"] }
tokio = { version = "1", features = ["full"] }
serde_json = "1"
```
</Tab>
</Tabs>
## Steps [#steps]
<Steps>
<Step>
### Search for images [#search-for-images]
Call `GET /v1/google/images` with a `q` parameter.
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```python
import requests
API_KEY = "YOUR_API_KEY"
response = requests.get(
"https://api.autom.dev/v1/google/images",
headers={"x-api-key": API_KEY},
params={"query": "electric car charging station", "gl": "us", "hl": "en"},
)
data = response.json()
```
</Tab>
<Tab value="TypeScript">
```typescript
const API_KEY = "YOUR_API_KEY";
const params = new URLSearchParams({ q: "electric car charging station", gl: "us", hl: "en" });
const response = await fetch(`https://api.autom.dev/v1/google/images?${params}`, {
headers: { "x-api-key": API_KEY },
});
const data = await response.json();
```
</Tab>
<Tab value="PHP">
```php
<?php
$apiKey = "YOUR_API_KEY";
$params = http_build_query(["query" => "electric car charging station", "gl" => "us", "hl" => "en"]);
$ch = curl_init("https://api.autom.dev/v1/google/images?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
```
</Tab>
<Tab value="Go">
```go
package main
import (
"encoding/json"
"io"
"net/http"
"net/url"
)
func main() {
params := url.Values{"query": {"electric car charging station"}, "gl": {"us"}, "hl": {"en"}}
req, _ := http.NewRequest("GET", "https://api.autom.dev/v1/google/images?"+params.Encode(), nil)
req.Header.Set("x-api-key", "YOUR_API_KEY")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var data map[string]any
json.Unmarshal(body, &data)
}
```
</Tab>
<Tab value="Java">
```java
import java.net.URI;
import java.net.http.*;
var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://api.autom.dev/v1/google/images?q=electric+car+charging+station&gl=us&hl=en"))
.header("x-api-key", "YOUR_API_KEY")
.GET().build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```
</Tab>
<Tab value="C#">
```csharp
using System.Net.Http;
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");
var body = await client.GetStringAsync(
"https://api.autom.dev/v1/google/images?q=electric+car+charging+station&gl=us&hl=en");
```
</Tab>
<Tab value="Rust">
```rust
#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
let data = reqwest::Client::new()
.get("https://api.autom.dev/v1/google/images")
.header("x-api-key", "YOUR_API_KEY")
.query(&[("query", "electric car charging station"), ("gl", "us"), ("hl", "en")])
.send().await?.json::<serde_json::Value>().await?;
println!("{:#?}", data);
Ok(())
}
```
</Tab>
</Tabs>
</Step>
<Step>
### Inspect the image results [#inspect-the-image-results]
Each item in `images` has `url` (direct image), `link` (source page), `title`, `domain`, `source`, `image_width`, and `image_height`.
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```python
for img in data.get("images", []):
print(f"[{img['position']}] {img['title']}")
print(f" Image : {img['url']}")
print(f" Source: {img['source']} — {img['image_width']}x{img['image_height']}px\n")
```
</Tab>
<Tab value="TypeScript">
```typescript
for (const img of data.images ?? []) {
console.log(`[${img.position}] ${img.title}`);
console.log(` Image : ${img.url}`);
console.log(` Source: ${img.source} — ${img.image_width}x${img.image_height}px\n`);
}
```
</Tab>
<Tab value="PHP">
```php
foreach ($data["images"] ?? [] as $img) {
echo "[{$img['position']}] {$img['title']}\n";
echo " Image : {$img['url']}\n";
echo " Source: {$img['source']} — {$img['image_width']}x{$img['image_height']}px\n\n";
}
```
</Tab>
<Tab value="Go">
```go
import "fmt"
for _, r := range data["images"].([]any) {
img := r.(map[string]any)
fmt.Printf("[%.0f] %s\n Image : %s\n Source: %s — %.0fx%.0fpx\n\n",
img["position"], img["title"], img["url"],
img["source"], img["image_width"], img["image_height"])
}
```
</Tab>
<Tab value="Java">
```java
import org.json.*;
var images = new JSONObject(response.body()).getJSONArray("images");
for (int i = 0; i < images.length(); i++) {
var img = images.getJSONObject(i);
System.out.printf("[%d] %s%n Image : %s%n Source: %s — %dx%dpx%n%n",
img.getInt("position"), img.getString("title"),
img.getString("url"), img.getString("source"),
img.getInt("image_width"), img.getInt("image_height"));
}
```
</Tab>
<Tab value="C#">
```csharp
using System.Text.Json;
var images = JsonDocument.Parse(body).RootElement.GetProperty("images").EnumerateArray();
foreach (var img in images)
{
Console.WriteLine($"[{img.GetProperty("position")}] {img.GetProperty("title")}");
Console.WriteLine($" Image : {img.GetProperty("url")}");
Console.WriteLine($" Source: {img.GetProperty("source")} — {img.GetProperty("image_width")}x{img.GetProperty("image_height")}px\n");
}
```
</Tab>
<Tab value="Rust">
```rust
if let Some(images) = data["images"].as_array() {
for img in images {
println!("[{}] {}", img["position"], img["title"].as_str().unwrap_or(""));
println!(" Image : {}", img["url"].as_str().unwrap_or(""));
println!(" Source: {} — {}x{}px\n",
img["source"].as_str().unwrap_or(""), img["image_width"], img["image_height"]);
}
}
```
</Tab>
</Tabs>
</Step>
<Step>
### Build an image catalog filtered by minimum size [#build-an-image-catalog-filtered-by-minimum-size]
Filter out thumbnails and save only high-resolution images.
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```python
import csv, requests
API_KEY = "YOUR_API_KEY"
QUERY = "electric car charging station"
MIN_WIDTH = 800
def fetch_images(query: str, pages: int = 2) -> list:
results = []
for page in range(1, pages + 1):
r = requests.get("https://api.autom.dev/v1/google/images",
headers={"x-api-key": API_KEY},
params={"query": query, "gl": "us", "hl": "en", "page": page})
results.extend(r.json().get("images", []))
return results
large = [img for img in fetch_images(QUERY) if img.get("image_width", 0) >= MIN_WIDTH]
with open("image_catalog.csv", "w", newline="") as f:
writer = csv.DictWriter(f, fieldnames=["position", "title", "url", "source", "image_width", "image_height"])
writer.writeheader()
writer.writerows(large)
print(f"Saved {len(large)} high-res images to image_catalog.csv")
```
</Tab>
<Tab value="TypeScript">
```typescript
import { writeFileSync } from "fs";
const API_KEY = "YOUR_API_KEY";
const MIN_WIDTH = 800;
async function fetchImages(query: string, pages = 2): Promise<any[]> {
const all: any[] = [];
for (let page = 1; page <= pages; page++) {
const params = new URLSearchParams({ q: query, gl: "us", hl: "en", page: String(page) });
const res = await fetch(`https://api.autom.dev/v1/google/images?${params}`, {
headers: { "x-api-key": API_KEY },
});
all.push(...((await res.json()).images ?? []));
}
return all;
}
const images = await fetchImages("electric car charging station");
const large = images.filter(img => (img.image_width ?? 0) >= MIN_WIDTH);
writeFileSync("image_catalog.json", JSON.stringify(large, null, 2));
console.log(`Saved ${large.length} high-res images to image_catalog.json`);
```
</Tab>
<Tab value="PHP">
```php
<?php
$apiKey = "YOUR_API_KEY";
$query = "electric car charging station";
$minWidth = 800;
function fetchImages(string $apiKey, string $query, int $pages = 2): array {
$all = [];
for ($page = 1; $page <= $pages; $page++) {
$params = http_build_query(["query" => $query, "gl" => "us", "hl" => "en", "page" => $page]);
$ch = curl_init("https://api.autom.dev/v1/google/images?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
$all = array_merge($all, $data["images"] ?? []);
}
return $all;
}
$large = array_filter(fetchImages($apiKey, $query), fn($img) => ($img["image_width"] ?? 0) >= $minWidth);
file_put_contents("image_catalog.json", json_encode(array_values($large), JSON_PRETTY_PRINT));
echo "Saved " . count($large) . " high-res images to image_catalog.json\n";
```
</Tab>
<Tab value="Go">
```go
package main
import (
"encoding/json"
"fmt"
"io"
"net/http"
"net/url"
"os"
"strconv"
)
func fetchImages(apiKey, query string, pages int) []map[string]any {
var all []map[string]any
for page := 1; page <= pages; page++ {
params := url.Values{"query": {query}, "gl": {"us"}, "hl": {"en"}, "page": {strconv.Itoa(page)}}
req, _ := http.NewRequest("GET", "https://api.autom.dev/v1/google/images?"+params.Encode(), nil)
req.Header.Set("x-api-key", apiKey)
resp, _ := http.DefaultClient.Do(req)
body, _ := io.ReadAll(resp.Body)
resp.Body.Close()
var data map[string]any
json.Unmarshal(body, &data)
for _, r := range data["images"].([]any) {
all = append(all, r.(map[string]any))
}
}
return all
}
func main() {
images := fetchImages("YOUR_API_KEY", "electric car charging station", 2)
minWidth := float64(800)
var large []map[string]any
for _, img := range images {
if img["image_width"].(float64) >= minWidth {
large = append(large, img)
}
}
b, _ := json.MarshalIndent(large, "", " ")
os.WriteFile("image_catalog.json", b, 0644)
fmt.Printf("Saved %d high-res images to image_catalog.json\n", len(large))
}
```
</Tab>
<Tab value="Java">
```java
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
import java.nio.file.*;
import java.util.*;
import org.json.*;
public class Main {
public static void main(String[] args) throws Exception {
var apiKey = "YOUR_API_KEY";
var query = URLEncoder.encode("electric car charging station", StandardCharsets.UTF_8);
var minWidth = 800;
var client = HttpClient.newHttpClient();
var all = new JSONArray();
for (int page = 1; page <= 2; page++) {
var url = "https://api.autom.dev/v1/google/images?q=" + query + "&gl=us&hl=en&page=" + page;
var req = HttpRequest.newBuilder().uri(URI.create(url))
.header("x-api-key", apiKey).GET().build();
var resp = client.send(req, HttpResponse.BodyHandlers.ofString());
var imgs = new JSONObject(resp.body()).getJSONArray("images");
for (int i = 0; i < imgs.length(); i++) all.put(imgs.get(i));
}
var large = new JSONArray();
for (int i = 0; i < all.length(); i++) {
var img = all.getJSONObject(i);
if (img.getInt("image_width") >= minWidth) large.put(img);
}
Files.writeString(Path.of("image_catalog.json"), large.toString(2));
System.out.println("Saved " + large.length() + " high-res images to image_catalog.json");
}
}
```
</Tab>
<Tab value="C#">
```csharp
using System.Net.Http;
using System.Text.Json;
var apiKey = "YOUR_API_KEY";
var minWidth = 800;
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", apiKey);
var all = new List<JsonElement>();
for (int page = 1; page <= 2; page++)
{
var body = await client.GetStringAsync(
$"https://api.autom.dev/v1/google/images?q=electric+car+charging+station&gl=us&hl=en&page={page}");
var json = JsonDocument.Parse(body).RootElement;
foreach (var img in json.GetProperty("images").EnumerateArray())
all.Add(img);
}
var large = all.Where(img => img.GetProperty("image_width").GetInt32() >= minWidth).ToList();
File.WriteAllText("image_catalog.json", JsonSerializer.Serialize(large, new JsonSerializerOptions { WriteIndented = true }));
Console.WriteLine($"Saved {large.Count} high-res images to image_catalog.json");
```
</Tab>
<Tab value="Rust">
```rust
use reqwest::Client;
use serde_json::Value;
use std::fs;
async fn fetch_images(client: &Client, api_key: &str, query: &str, pages: u32) -> Vec<Value> {
let mut all = Vec::new();
for page in 1..=pages {
let data = client.get("https://api.autom.dev/v1/google/images")
.header("x-api-key", api_key)
.query(&[("query", query), ("gl", "us"), ("hl", "en"), ("page", &page.to_string())])
.send().await.unwrap().json::<Value>().await.unwrap();
if let Some(imgs) = data["images"].as_array() { all.extend(imgs.clone()); }
}
all
}
#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
let client = Client::new();
let images = fetch_images(&client, "YOUR_API_KEY", "electric car charging station", 2).await;
let large: Vec<&Value> = images.iter()
.filter(|img| img["image_width"].as_i64().unwrap_or(0) >= 800)
.collect();
fs::write("image_catalog.json", serde_json::to_string_pretty(&large).unwrap()).unwrap();
println!("Saved {} high-res images to image_catalog.json", large.len());
Ok(())
}
```
</Tab>
</Tabs>
</Step>
</Steps>
<Callout type="info">
The `url` field in each result is the direct link to the image file. Always verify you have the rights to use an image before including it in a dataset or product.
</Callout>
# Monitor Google News (/playbooks/autom-google-news)
## Overview [#overview]
This playbook builds a **news monitoring pipeline**: query Google News for a brand name, product, or topic and collect all article titles, sources, and publication dates. Run it on a cron schedule to detect press coverage as soon as it appears.
## Prerequisites [#prerequisites]
* An Autom API key — get one at [app.autom.dev](https://app.autom.dev)
* Install dependencies for your language:
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```bash
pip install requests
```
</Tab>
<Tab value="TypeScript">
No extra dependencies — uses the native `fetch` API (Node 18+).
</Tab>
<Tab value="PHP">
`curl` extension enabled (on by default in most PHP installs).
</Tab>
<Tab value="Go">
No extra dependencies — uses the `net/http` standard library (Go 1.18+).
</Tab>
<Tab value="Java">
No extra dependencies — uses `java.net.http` (Java 11+).
</Tab>
<Tab value="C#">
No extra dependencies — uses `System.Net.Http` (.NET 6+).
</Tab>
<Tab value="Rust">
```toml
# Cargo.toml
[dependencies]
reqwest = { version = "0.12", features = ["json"] }
tokio = { version = "1", features = ["full"] }
serde_json = "1"
```
</Tab>
</Tabs>
## Steps [#steps]
<Steps>
<Step>
### Fetch latest news articles [#fetch-latest-news-articles]
Call `GET /v1/google/news` with the keyword you want to monitor.
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```python
import requests
API_KEY = "YOUR_API_KEY"
response = requests.get(
"https://api.autom.dev/v1/google/news",
headers={"x-api-key": API_KEY},
params={"query": "OpenAI", "gl": "us", "hl": "en"},
)
data = response.json()
```
</Tab>
<Tab value="TypeScript">
```typescript
const API_KEY = "YOUR_API_KEY";
const params = new URLSearchParams({ q: "OpenAI", gl: "us", hl: "en" });
const response = await fetch(`https://api.autom.dev/v1/google/news?${params}`, {
headers: { "x-api-key": API_KEY },
});
const data = await response.json();
```
</Tab>
<Tab value="PHP">
```php
<?php
$apiKey = "YOUR_API_KEY";
$params = http_build_query(["query" => "OpenAI", "gl" => "us", "hl" => "en"]);
$ch = curl_init("https://api.autom.dev/v1/google/news?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
```
</Tab>
<Tab value="Go">
```go
package main
import (
"encoding/json"
"io"
"net/http"
"net/url"
)
func main() {
params := url.Values{"query": {"OpenAI"}, "gl": {"us"}, "hl": {"en"}}
req, _ := http.NewRequest("GET", "https://api.autom.dev/v1/google/news?"+params.Encode(), nil)
req.Header.Set("x-api-key", "YOUR_API_KEY")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var data map[string]any
json.Unmarshal(body, &data)
// use data below
}
```
</Tab>
<Tab value="Java">
```java
import java.net.URI;
import java.net.http.*;
var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://api.autom.dev/v1/google/news?q=OpenAI&gl=us&hl=en"))
.header("x-api-key", "YOUR_API_KEY")
.GET().build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```
</Tab>
<Tab value="C#">
```csharp
using System.Net.Http;
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");
var body = await client.GetStringAsync(
"https://api.autom.dev/v1/google/news?q=OpenAI&gl=us&hl=en");
Console.WriteLine(body);
```
</Tab>
<Tab value="Rust">
```rust
#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
let data = reqwest::Client::new()
.get("https://api.autom.dev/v1/google/news")
.header("x-api-key", "YOUR_API_KEY")
.query(&[("query", "OpenAI"), ("gl", "us"), ("hl", "en")])
.send().await?
.json::<serde_json::Value>().await?;
println!("{:#?}", data);
Ok(())
}
```
</Tab>
</Tabs>
</Step>
<Step>
### Extract and display articles [#extract-and-display-articles]
Each item in `organic_results` has `title`, `link`, `source`, `date`, and `snippet`.
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```python
for article in data.get("organic_results", []):
print(f"[{article['date']}] {article['title']}")
print(f" Source : {article['source']}")
print(f" URL : {article['link']}\n")
```
</Tab>
<Tab value="TypeScript">
```typescript
for (const article of data.organic_results ?? []) {
console.log(`[${article.date}] ${article.title}`);
console.log(` Source : ${article.source}`);
console.log(` URL : ${article.link}\n`);
}
```
</Tab>
<Tab value="PHP">
```php
foreach ($data["organic_results"] ?? [] as $article) {
echo "[{$article['date']}] {$article['title']}\n";
echo " Source : {$article['source']}\n";
echo " URL : {$article['link']}\n\n";
}
```
</Tab>
<Tab value="Go">
```go
results := data["organic_results"].([]any)
for _, r := range results {
a := r.(map[string]any)
fmt.Printf("[%s] %s\n Source : %s\n URL : %s\n\n",
a["date"], a["title"], a["source"], a["link"])
}
```
</Tab>
<Tab value="Java">
```java
import org.json.*;
var json = new JSONObject(response.body());
var results = json.getJSONArray("organic_results");
for (int i = 0; i < results.length(); i++) {
var a = results.getJSONObject(i);
System.out.printf("[%s] %s%n Source : %s%n URL : %s%n%n",
a.getString("date"), a.getString("title"),
a.getString("source"), a.getString("link"));
}
```
</Tab>
<Tab value="C#">
```csharp
using System.Text.Json;
var json = JsonDocument.Parse(body);
var results = json.RootElement.GetProperty("organic_results").EnumerateArray();
foreach (var a in results)
{
Console.WriteLine($"[{a.GetProperty("date")}] {a.GetProperty("title")}");
Console.WriteLine($" Source : {a.GetProperty("source")}");
Console.WriteLine($" URL : {a.GetProperty("link")}\n");
}
```
</Tab>
<Tab value="Rust">
```rust
if let Some(articles) = data["organic_results"].as_array() {
for a in articles {
println!("[{}] {}", a["date"].as_str().unwrap_or(""), a["title"].as_str().unwrap_or(""));
println!(" Source : {}", a["source"].as_str().unwrap_or(""));
println!(" URL : {}\n", a["link"].as_str().unwrap_or(""));
}
}
```
</Tab>
</Tabs>
</Step>
<Step>
### Build a monitoring pipeline with deduplication [#build-a-monitoring-pipeline-with-deduplication]
Store seen article URLs so repeated runs don't produce duplicate alerts.
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```python
import json, requests
from pathlib import Path
API_KEY = "YOUR_API_KEY"
KEYWORDS = ["OpenAI", "Anthropic", "Mistral AI"]
SEEN_FILE = Path("seen_articles.json")
def load_seen() -> set:
return set(json.loads(SEEN_FILE.read_text())) if SEEN_FILE.exists() else set()
def save_seen(seen: set) -> None:
SEEN_FILE.write_text(json.dumps(list(seen)))
def fetch_news(query: str) -> list:
r = requests.get("https://api.autom.dev/v1/google/news",
headers={"x-api-key": API_KEY}, params={"query": query, "gl": "us", "hl": "en"})
return r.json().get("organic_results", [])
seen = load_seen()
new_articles = []
for keyword in KEYWORDS:
for article in fetch_news(keyword):
if article["link"] not in seen:
seen.add(article["link"])
new_articles.append({**article, "keyword": keyword})
save_seen(seen)
print(f"Found {len(new_articles)} new article(s):")
for a in new_articles:
print(f" [{a['keyword']}] {a['title']} — {a['source']}")
```
</Tab>
<Tab value="TypeScript">
```typescript
import { readFileSync, writeFileSync, existsSync } from "fs";
const API_KEY = "YOUR_API_KEY";
const KEYWORDS = ["OpenAI", "Anthropic", "Mistral AI"];
const SEEN_FILE = "seen_articles.json";
function loadSeen(): Set<string> {
return existsSync(SEEN_FILE)
? new Set(JSON.parse(readFileSync(SEEN_FILE, "utf-8")))
: new Set();
}
async function fetchNews(query: string): Promise<any[]> {
const params = new URLSearchParams({ q: query, gl: "us", hl: "en" });
const res = await fetch(`https://api.autom.dev/v1/google/news?${params}`, {
headers: { "x-api-key": API_KEY },
});
return (await res.json()).organic_results ?? [];
}
const seen = loadSeen();
const newArticles: any[] = [];
for (const keyword of KEYWORDS) {
for (const article of await fetchNews(keyword)) {
if (!seen.has(article.link)) {
seen.add(article.link);
newArticles.push({ ...article, keyword });
}
}
}
writeFileSync(SEEN_FILE, JSON.stringify([...seen]));
console.log(`Found ${newArticles.length} new article(s):`);
for (const a of newArticles) console.log(` [${a.keyword}] ${a.title} — ${a.source}`);
```
</Tab>
<Tab value="PHP">
```php
<?php
$apiKey = "YOUR_API_KEY";
$keywords = ["OpenAI", "Anthropic", "Mistral AI"];
$seenFile = "seen_articles.json";
$seen = file_exists($seenFile) ? array_flip(json_decode(file_get_contents($seenFile), true)) : [];
$newArticles = [];
foreach ($keywords as $keyword) {
$params = http_build_query(["query" => $keyword, "gl" => "us", "hl" => "en"]);
$ch = curl_init("https://api.autom.dev/v1/google/news?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
foreach ($data["organic_results"] ?? [] as $article) {
if (!isset($seen[$article["link"]])) {
$seen[$article["link"]] = true;
$newArticles[] = array_merge($article, ["keyword" => $keyword]);
}
}
}
file_put_contents($seenFile, json_encode(array_keys($seen)));
echo "Found " . count($newArticles) . " new article(s):\n";
foreach ($newArticles as $a) echo " [{$a['keyword']}] {$a['title']} — {$a['source']}\n";
```
</Tab>
<Tab value="Go">
```go
package main
import (
"encoding/json"
"fmt"
"io"
"net/http"
"net/url"
"os"
)
func fetchNews(apiKey, query string) []map[string]any {
params := url.Values{"query": {query}, "gl": {"us"}, "hl": {"en"}}
req, _ := http.NewRequest("GET", "https://api.autom.dev/v1/google/news?"+params.Encode(), nil)
req.Header.Set("x-api-key", apiKey)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var data map[string]any
json.Unmarshal(body, &data)
var out []map[string]any
for _, r := range data["organic_results"].([]any) {
out = append(out, r.(map[string]any))
}
return out
}
func main() {
apiKey := "YOUR_API_KEY"
keywords := []string{"OpenAI", "Anthropic", "Mistral AI"}
seen := map[string]bool{}
if b, err := os.ReadFile("seen_articles.json"); err == nil {
var links []string
json.Unmarshal(b, &links)
for _, l := range links { seen[l] = true }
}
var newCount int
for _, kw := range keywords {
for _, a := range fetchNews(apiKey, kw) {
link := a["link"].(string)
if !seen[link] {
seen[link] = true
fmt.Printf(" [%s] %s — %s\n", kw, a["title"], a["source"])
newCount++
}
}
}
links := make([]string, 0, len(seen))
for l := range seen { links = append(links, l) }
b, _ := json.Marshal(links)
os.WriteFile("seen_articles.json", b, 0644)
fmt.Printf("Found %d new article(s).\n", newCount)
}
```
</Tab>
<Tab value="Java">
```java
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
import java.nio.file.*;
import java.util.*;
import org.json.*;
public class Main {
static HttpClient client = HttpClient.newHttpClient();
static String API_KEY = "YOUR_API_KEY";
public static void main(String[] args) throws Exception {
var keywords = List.of("OpenAI", "Anthropic", "Mistral AI");
var seenPath = Path.of("seen_articles.json");
var seen = new HashSet<String>();
if (Files.exists(seenPath)) {
var arr = new JSONArray(Files.readString(seenPath));
for (int i = 0; i < arr.length(); i++) seen.add(arr.getString(i));
}
int newCount = 0;
for (var kw : keywords) {
var q = URLEncoder.encode(kw, StandardCharsets.UTF_8);
var url = "https://api.autom.dev/v1/google/news?q=" + q + "&gl=us&hl=en";
var req = HttpRequest.newBuilder().uri(URI.create(url))
.header("x-api-key", API_KEY).GET().build();
var resp = client.send(req, HttpResponse.BodyHandlers.ofString());
var results = new JSONObject(resp.body()).getJSONArray("organic_results");
for (int i = 0; i < results.length(); i++) {
var a = results.getJSONObject(i);
var link = a.getString("link");
if (!seen.contains(link)) {
seen.add(link);
System.out.printf(" [%s] %s — %s%n", kw, a.getString("title"), a.getString("source"));
newCount++;
}
}
}
Files.writeString(seenPath, new JSONArray(seen).toString());
System.out.println("Found " + newCount + " new article(s).");
}
}
```
</Tab>
<Tab value="C#">
```csharp
using System.Net.Http;
using System.Text.Json;
var apiKey = "YOUR_API_KEY";
var keywords = new[] { "OpenAI", "Anthropic", "Mistral AI" };
var seenFile = "seen_articles.json";
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", apiKey);
var seen = File.Exists(seenFile)
? JsonSerializer.Deserialize<HashSet<string>>(File.ReadAllText(seenFile))!
: new HashSet<string>();
int newCount = 0;
foreach (var keyword in keywords)
{
var url = $"https://api.autom.dev/v1/google/news?q={Uri.EscapeDataString(keyword)}&gl=us&hl=en";
var body = await client.GetStringAsync(url);
var json = JsonDocument.Parse(body).RootElement;
foreach (var a in json.GetProperty("organic_results").EnumerateArray())
{
var link = a.GetProperty("link").GetString()!;
if (seen.Add(link))
{
Console.WriteLine($" [{keyword}] {a.GetProperty("title")} — {a.GetProperty("source")}");
newCount++;
}
}
}
File.WriteAllText(seenFile, JsonSerializer.Serialize(seen));
Console.WriteLine($"Found {newCount} new article(s).");
```
</Tab>
<Tab value="Rust">
```rust
use reqwest::Client;
use serde_json::Value;
use std::{collections::HashSet, fs, path::Path};
async fn fetch_news(client: &Client, api_key: &str, query: &str) -> Vec<Value> {
let data = client
.get("https://api.autom.dev/v1/google/news")
.header("x-api-key", api_key)
.query(&[("query", query), ("gl", "us"), ("hl", "en")])
.send().await.unwrap().json::<Value>().await.unwrap();
data["organic_results"].as_array().cloned().unwrap_or_default()
}
#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
let client = Client::new();
let api_key = "YOUR_API_KEY";
let keywords = ["OpenAI", "Anthropic", "Mistral AI"];
let seen_path = Path::new("seen_articles.json");
let mut seen: HashSet<String> = if seen_path.exists() {
serde_json::from_str::<Vec<String>>(&fs::read_to_string(seen_path).unwrap())
.unwrap().into_iter().collect()
} else { HashSet::new() };
let mut new_count = 0;
for keyword in &keywords {
for article in fetch_news(&client, api_key, keyword).await {
let link = article["link"].as_str().unwrap_or("").to_string();
if seen.insert(link) {
println!(" [{}] {} — {}", keyword, article["title"].as_str().unwrap_or(""), article["source"].as_str().unwrap_or(""));
new_count += 1;
}
}
}
let seen_vec: Vec<&String> = seen.iter().collect();
fs::write(seen_path, serde_json::to_string(&seen_vec).unwrap()).unwrap();
println!("Found {new_count} new article(s).");
Ok(())
}
```
</Tab>
</Tabs>
</Step>
</Steps>
<Callout type="info">
Schedule this script with a cron job (e.g. every hour) or a task scheduler to receive continuous coverage monitoring. Combine multiple keywords in one run to minimize credit usage.
</Callout>
# Scrape Google Search Results (/playbooks/autom-google-search)
## Overview [#overview]
In this playbook you will build a script that queries Google Search and extracts structured organic results — positions, titles, URLs, and snippets — for any keyword. A typical use case is **rank tracking**: run this on a schedule to monitor where your pages appear for target keywords.
The endpoint returns up to 10 organic results per page and supports pagination, country (`gl`) and language (`hl`) targeting.
## Prerequisites [#prerequisites]
* An Autom API key — get one at [app.autom.dev](https://app.autom.dev)
* Install dependencies for your language:
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```bash
pip install requests
```
</Tab>
<Tab value="TypeScript">
No extra dependencies — uses the native `fetch` API (Node 18+).
</Tab>
<Tab value="PHP">
`curl` extension enabled (on by default in most PHP installs).
</Tab>
<Tab value="Go">
No extra dependencies — uses the `net/http` standard library (Go 1.18+).
</Tab>
<Tab value="Java">
No extra dependencies — uses `java.net.http` (Java 11+).
</Tab>
<Tab value="C#">
No extra dependencies — uses `System.Net.Http` (.NET 6+).
</Tab>
<Tab value="Rust">
```toml
# Cargo.toml
[dependencies]
reqwest = { version = "0.12", features = ["json"] }
tokio = { version = "1", features = ["full"] }
serde_json = "1"
```
</Tab>
</Tabs>
## Steps [#steps]
<Steps>
<Step>
### Make your first search request [#make-your-first-search-request]
Call `GET /v1/google/search` with the `q` parameter and your API key in the `x-api-key` header.
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```python
import requests
API_KEY = "YOUR_API_KEY"
response = requests.get(
"https://api.autom.dev/v1/google/search",
headers={"x-api-key": API_KEY},
params={"query": "best python web scraping libraries", "gl": "us", "hl": "en"},
)
data = response.json()
print(data)
```
</Tab>
<Tab value="TypeScript">
```typescript
const API_KEY = "YOUR_API_KEY";
const params = new URLSearchParams({
q: "best python web scraping libraries",
gl: "us",
hl: "en",
});
const response = await fetch(
`https://api.autom.dev/v1/google/search?${params}`,
{ headers: { "x-api-key": API_KEY } },
);
const data = await response.json();
console.log(data);
```
</Tab>
<Tab value="PHP">
```php
<?php
$apiKey = "YOUR_API_KEY";
$params = http_build_query([
"query" => "best python web scraping libraries",
"gl" => "us",
"hl" => "en",
]);
$ch = curl_init("https://api.autom.dev/v1/google/search?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($data);
```
</Tab>
<Tab value="Go">
```go
package main
import (
"encoding/json"
"fmt"
"io"
"net/http"
"net/url"
)
func main() {
apiKey := "YOUR_API_KEY"
params := url.Values{}
params.Set("query", "best python web scraping libraries")
params.Set("gl", "us")
params.Set("hl", "en")
req, _ := http.NewRequest("GET",
"https://api.autom.dev/v1/google/search?"+params.Encode(), nil)
req.Header.Set("x-api-key", apiKey)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var data map[string]any
json.Unmarshal(body, &data)
fmt.Println(data)
}
```
</Tab>
<Tab value="Java">
```java
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
public class Main {
public static void main(String[] args) throws Exception {
var apiKey = "YOUR_API_KEY";
var q = URLEncoder.encode("best python web scraping libraries", StandardCharsets.UTF_8);
var url = "https://api.autom.dev/v1/google/search?q=" + q + "&gl=us&hl=en";
var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("x-api-key", apiKey)
.GET()
.build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}
```
</Tab>
<Tab value="C#">
```csharp
using System.Net.Http;
var apiKey = "YOUR_API_KEY";
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", apiKey);
var url = "https://api.autom.dev/v1/google/search?q=best+python+web+scraping+libraries&gl=us&hl=en";
var response = await client.GetAsync(url);
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
```
</Tab>
<Tab value="Rust">
```rust
use reqwest::header;
#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
let client = reqwest::Client::new();
let response = client
.get("https://api.autom.dev/v1/google/search")
.header("x-api-key", "YOUR_API_KEY")
.query(&[("query", "best python web scraping libraries"), ("gl", "us"), ("hl", "en")])
.send()
.await?
.json::<serde_json::Value>()
.await?;
println!("{:#?}", response);
Ok(())
}
```
</Tab>
</Tabs>
</Step>
<Step>
### Parse the organic results [#parse-the-organic-results]
The response contains an `organic_results` array. Each entry has `position`, `title`, `link`, `snippet`, `domain`, and `source`.
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```python
for result in data["organic_results"]:
print(f"[{result['position']}] {result['title']}")
print(f" URL: {result['link']}")
print(f" {result.get('snippet', '')}")
print()
```
</Tab>
<Tab value="TypeScript">
```typescript
for (const result of data.organic_results) {
console.log(`[${result.position}] ${result.title}`);
console.log(` URL: ${result.link}`);
console.log(` ${result.snippet ?? ""}`);
console.log();
}
```
</Tab>
<Tab value="PHP">
```php
foreach ($data["organic_results"] as $result) {
echo "[{$result['position']}] {$result['title']}\n";
echo " URL: {$result['link']}\n";
echo " " . ($result['snippet'] ?? "") . "\n\n";
}
```
</Tab>
<Tab value="Go">
```go
results := data["organic_results"].([]any)
for _, r := range results {
item := r.(map[string]any)
fmt.Printf("[%.0f] %s\n", item["position"], item["title"])
fmt.Printf(" URL: %s\n", item["link"])
fmt.Printf(" %s\n\n", item["snippet"])
}
```
</Tab>
<Tab value="Java">
```java
import org.json.JSONArray;
import org.json.JSONObject;
// Add org.json:json to your build tool, or parse manually
var json = new JSONObject(response.body());
var results = json.getJSONArray("organic_results");
for (int i = 0; i < results.length(); i++) {
var r = results.getJSONObject(i);
System.out.printf("[%d] %s%n", r.getInt("position"), r.getString("title"));
System.out.printf(" URL: %s%n%n", r.getString("link"));
}
```
</Tab>
<Tab value="C#">
```csharp
using System.Text.Json;
var json = JsonDocument.Parse(body);
var results = json.RootElement.GetProperty("organic_results").EnumerateArray();
foreach (var result in results)
{
Console.WriteLine($"[{result.GetProperty("position")}] {result.GetProperty("title")}");
Console.WriteLine($" URL: {result.GetProperty("link")}");
Console.WriteLine();
}
```
</Tab>
<Tab value="Rust">
```rust
if let Some(results) = response["organic_results"].as_array() {
for result in results {
println!(
"[{}] {}",
result["position"],
result["title"].as_str().unwrap_or("")
);
println!(" URL: {}", result["link"].as_str().unwrap_or(""));
println!(" {}", result["snippet"].as_str().unwrap_or(""));
println!();
}
}
```
</Tab>
</Tabs>
</Step>
<Step>
### Handle pagination [#handle-pagination]
Use the `page` parameter to fetch subsequent pages. The response includes a `pagination` object with `has_next_page` and `next` page number.
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```python
import requests
API_KEY = "YOUR_API_KEY"
QUERY = "best python web scraping libraries"
def fetch_all_results(query: str, max_pages: int = 3) -> list:
all_results = []
page = 1
while page <= max_pages:
response = requests.get(
"https://api.autom.dev/v1/google/search",
headers={"x-api-key": API_KEY},
params={"query": query, "gl": "us", "hl": "en", "page": page},
)
data = response.json()
all_results.extend(data.get("organic_results", []))
if not data.get("pagination", {}).get("has_next_page"):
break
page += 1
return all_results
results = fetch_all_results(QUERY)
for r in results:
print(f"[{r['position']}] {r['title']} — {r['link']}")
```
</Tab>
<Tab value="TypeScript">
```typescript
const API_KEY = "YOUR_API_KEY";
async function fetchAllResults(query: string, maxPages = 3) {
const allResults: any[] = [];
let page = 1;
while (page <= maxPages) {
const params = new URLSearchParams({ q: query, gl: "us", hl: "en", page: String(page) });
const res = await fetch(`https://api.autom.dev/v1/google/search?${params}`, {
headers: { "x-api-key": API_KEY },
});
const data = await res.json();
allResults.push(...(data.organic_results ?? []));
if (!data.pagination?.has_next_page) break;
page++;
}
return allResults;
}
const results = await fetchAllResults("best python web scraping libraries");
for (const r of results) {
console.log(`[${r.position}] ${r.title} — ${r.link}`);
}
```
</Tab>
<Tab value="PHP">
```php
<?php
function fetchAllResults(string $apiKey, string $query, int $maxPages = 3): array {
$allResults = [];
$page = 1;
while ($page <= $maxPages) {
$params = http_build_query(["query" => $query, "gl" => "us", "hl" => "en", "page" => $page]);
$ch = curl_init("https://api.autom.dev/v1/google/search?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
$allResults = array_merge($allResults, $data["organic_results"] ?? []);
if (!($data["pagination"]["has_next_page"] ?? false)) break;
$page++;
}
return $allResults;
}
$results = fetchAllResults("YOUR_API_KEY", "best python web scraping libraries");
foreach ($results as $r) {
echo "[{$r['position']}] {$r['title']} — {$r['link']}\n";
}
```
</Tab>
<Tab value="Go">
```go
package main
import (
"encoding/json"
"fmt"
"io"
"net/http"
"net/url"
"strconv"
)
func fetchAllResults(apiKey, query string, maxPages int) []map[string]any {
var all []map[string]any
for page := 1; page <= maxPages; page++ {
params := url.Values{"query": {query}, "gl": {"us"}, "hl": {"en"}, "page": {strconv.Itoa(page)}}
req, _ := http.NewRequest("GET", "https://api.autom.dev/v1/google/search?"+params.Encode(), nil)
req.Header.Set("x-api-key", apiKey)
resp, _ := http.DefaultClient.Do(req)
body, _ := io.ReadAll(resp.Body)
resp.Body.Close()
var data map[string]any
json.Unmarshal(body, &data)
if items, ok := data["organic_results"].([]any); ok {
for _, item := range items {
all = append(all, item.(map[string]any))
}
}
pagination, _ := data["pagination"].(map[string]any)
if pagination["has_next_page"] != true {
break
}
}
return all
}
func main() {
results := fetchAllResults("YOUR_API_KEY", "best python web scraping libraries", 3)
for _, r := range results {
fmt.Printf("[%.0f] %s — %s\n", r["position"], r["title"], r["link"])
}
}
```
</Tab>
<Tab value="Java">
```java
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
import java.util.*;
import org.json.*;
public class Main {
static HttpClient client = HttpClient.newHttpClient();
static String API_KEY = "YOUR_API_KEY";
static List<JSONObject> fetchAllResults(String query, int maxPages) throws Exception {
var all = new ArrayList<JSONObject>();
var q = URLEncoder.encode(query, StandardCharsets.UTF_8);
for (int page = 1; page <= maxPages; page++) {
var url = "https://api.autom.dev/v1/google/search?q=" + q + "&gl=us&hl=en&page=" + page;
var request = HttpRequest.newBuilder().uri(URI.create(url))
.header("x-api-key", API_KEY).GET().build();
var resp = client.send(request, HttpResponse.BodyHandlers.ofString());
var json = new JSONObject(resp.body());
var results = json.optJSONArray("organic_results");
if (results != null) {
for (int i = 0; i < results.length(); i++) all.add(results.getJSONObject(i));
}
if (!json.optJSONObject("pagination").optBoolean("has_next_page")) break;
}
return all;
}
public static void main(String[] args) throws Exception {
for (var r : fetchAllResults("best python web scraping libraries", 3)) {
System.out.printf("[%d] %s — %s%n", r.getInt("position"), r.getString("title"), r.getString("link"));
}
}
}
```
</Tab>
<Tab value="C#">
```csharp
using System.Net.Http;
using System.Text.Json;
var apiKey = "YOUR_API_KEY";
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", apiKey);
var allResults = new List<JsonElement>();
int page = 1, maxPages = 3;
while (page <= maxPages)
{
var url = $"https://api.autom.dev/v1/google/search?q=best+python+web+scraping+libraries&gl=us&hl=en&page={page}";
var response = await client.GetAsync(url);
var body = await response.Content.ReadAsStringAsync();
var json = JsonDocument.Parse(body).RootElement;
foreach (var result in json.GetProperty("organic_results").EnumerateArray())
allResults.Add(result);
var hasNext = json.GetProperty("pagination").GetProperty("has_next_page").GetBoolean();
if (!hasNext) break;
page++;
}
foreach (var r in allResults)
Console.WriteLine($"[{r.GetProperty("position")}] {r.GetProperty("title")} — {r.GetProperty("link")}");
```
</Tab>
<Tab value="Rust">
```rust
use reqwest::Client;
use serde_json::Value;
async fn fetch_all_results(client: &Client, api_key: &str, query: &str, max_pages: u32) -> Vec<Value> {
let mut all_results = Vec::new();
let mut page = 1u32;
while page <= max_pages {
let resp = client
.get("https://api.autom.dev/v1/google/search")
.header("x-api-key", api_key)
.query(&[("query", query), ("gl", "us"), ("hl", "en"), ("page", &page.to_string())])
.send().await.unwrap()
.json::<Value>().await.unwrap();
if let Some(results) = resp["organic_results"].as_array() {
all_results.extend(results.clone());
}
if !resp["pagination"]["has_next_page"].as_bool().unwrap_or(false) { break; }
page += 1;
}
all_results
}
#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
let client = Client::new();
let results = fetch_all_results(&client, "YOUR_API_KEY", "best python web scraping libraries", 3).await;
for r in &results {
println!("[{}] {} — {}", r["position"], r["title"].as_str().unwrap_or(""), r["link"].as_str().unwrap_or(""));
}
Ok(())
}
```
</Tab>
</Tabs>
</Step>
</Steps>
<Callout type="info">
Use the `gl` parameter to target a specific country (e.g. `fr` for France, `de` for Germany) and `hl` for the language of results. This is essential for accurate local rank tracking.
</Callout>
# Analyze a Page with AI (/playbooks/capturekit-ai-analysis)
## Overview [#overview]
The CaptureKit AI analysis endpoint combines screenshot capture with LLM-powered analysis. Pass any URL and a custom `prompt` — the API returns a structured JSON answer grounded in what the page actually looks like. Use it for **competitor audits**, **UX reviews**, or **automated content QA**.
## Prerequisites [#prerequisites]
* A CaptureKit API key — get one at [app.capturekit.dev](https://app.capturekit.dev)
* Install dependencies for your language:
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```bash
pip install requests
```
</Tab>
<Tab value="TypeScript">
No extra dependencies — uses the native `fetch` API (Node 18+).
</Tab>
<Tab value="PHP">
`curl` extension enabled (on by default).
</Tab>
<Tab value="Go">
No extra dependencies — uses `net/http` (Go 1.18+).
</Tab>
<Tab value="Java">
No extra dependencies — uses `java.net.http` (Java 11+).
</Tab>
<Tab value="C#">
No extra dependencies — uses `System.Net.Http` (.NET 6+).
</Tab>
<Tab value="Rust">
```toml
# Cargo.toml
[dependencies]
reqwest = { version = "0.12", features = ["json"] }
tokio = { version = "1", features = ["full"] }
serde_json = "1"
```
</Tab>
</Tabs>
## Steps [#steps]
<Steps>
<Step>
### Submit an analysis request [#submit-an-analysis-request]
Call `GET /v1/analyze` with the `url` and `prompt` parameters. The `prompt` shapes the AI's response.
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```python
import requests
API_KEY = "YOUR_API_KEY"
PROMPT = "Summarize the main value proposition of this page in 2 sentences. Then list the top 3 CTAs visible above the fold."
response = requests.get(
"https://api.capturekit.dev/v1/analyze",
headers={"x-api-key": API_KEY},
params={"url": "https://stripe.com", "prompt": PROMPT},
)
data = response.json()
print(data)
```
</Tab>
<Tab value="TypeScript">
```typescript
const API_KEY = "YOUR_API_KEY";
const PROMPT = "Summarize the main value proposition of this page in 2 sentences. Then list the top 3 CTAs visible above the fold.";
const params = new URLSearchParams({ url: "https://stripe.com", prompt: PROMPT });
const response = await fetch(`https://api.capturekit.dev/v1/analyze?${params}`, {
headers: { "x-api-key": API_KEY },
});
const data = await response.json();
console.log(data);
```
</Tab>
<Tab value="PHP">
```php
<?php
$apiKey = "YOUR_API_KEY";
$prompt = "Summarize the main value proposition of this page in 2 sentences. Then list the top 3 CTAs visible above the fold.";
$params = http_build_query(["url" => "https://stripe.com", "prompt" => $prompt]);
$ch = curl_init("https://api.capturekit.dev/v1/analyze?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($data);
```
</Tab>
<Tab value="Go">
```go
package main
import (
"encoding/json"
"fmt"
"io"
"net/http"
"net/url"
)
func main() {
params := url.Values{
"url": {"https://stripe.com"},
"prompt": {"Summarize the main value proposition in 2 sentences. List the top 3 CTAs above the fold."},
}
req, _ := http.NewRequest("GET", "https://api.capturekit.dev/v1/analyze?"+params.Encode(), nil)
req.Header.Set("x-api-key", "YOUR_API_KEY")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var data map[string]any
json.Unmarshal(body, &data)
fmt.Println(data)
}
```
</Tab>
<Tab value="Java">
```java
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
var client = HttpClient.newHttpClient();
var prompt = URLEncoder.encode("Summarize the value proposition in 2 sentences. List the top 3 CTAs above the fold.", StandardCharsets.UTF_8);
var request = HttpRequest.newBuilder()
.uri(URI.create("https://api.capturekit.dev/v1/analyze?url=https%3A%2F%2Fstripe.com&prompt=" + prompt))
.header("x-api-key", "YOUR_API_KEY").GET().build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```
</Tab>
<Tab value="C#">
```csharp
using System.Net.Http;
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");
var prompt = Uri.EscapeDataString("Summarize the value proposition in 2 sentences. List the top 3 CTAs above the fold.");
var body = await client.GetStringAsync(
$"https://api.capturekit.dev/v1/analyze?url=https%3A%2F%2Fstripe.com&prompt={prompt}");
Console.WriteLine(body);
```
</Tab>
<Tab value="Rust">
```rust
#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
let data = reqwest::Client::new()
.get("https://api.capturekit.dev/v1/analyze")
.header("x-api-key", "YOUR_API_KEY")
.query(&[
("url", "https://stripe.com"),
("prompt", "Summarize the value proposition in 2 sentences. List the top 3 CTAs above the fold."),
])
.send().await?.json::<serde_json::Value>().await?;
println!("{:#?}", data);
Ok(())
}
```
</Tab>
</Tabs>
</Step>
<Step>
### Read the AI analysis [#read-the-ai-analysis]
The response includes `analysis` (the AI's answer to your prompt), `screenshot_url`, and metadata like `title` and `description`.
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```python
print(f"Page : {data.get('title')}")
print(f"Preview : {data.get('screenshot_url')}")
print()
print("=== AI Analysis ===")
print(data.get("analysis", ""))
```
</Tab>
<Tab value="TypeScript">
```typescript
console.log(`Page : ${data.title}`);
console.log(`Preview : ${data.screenshot_url}\n`);
console.log("=== AI Analysis ===");
console.log(data.analysis);
```
</Tab>
<Tab value="PHP">
```php
echo "Page : {$data['title']}\n";
echo "Preview : {$data['screenshot_url']}\n\n";
echo "=== AI Analysis ===\n";
echo $data["analysis"] ?? "";
```
</Tab>
<Tab value="Go">
```go
fmt.Printf("Page : %v\nPreview : %v\n\n=== AI Analysis ===\n%v\n",
data["title"], data["screenshot_url"], data["analysis"])
```
</Tab>
<Tab value="Java">
```java
import org.json.*;
var d = new JSONObject(response.body());
System.out.printf("Page : %s%nPreview : %s%n%n=== AI Analysis ===%n%s%n",
d.getString("title"), d.getString("screenshot_url"), d.getString("analysis"));
```
</Tab>
<Tab value="C#">
```csharp
using System.Text.Json;
var d = JsonDocument.Parse(body).RootElement;
Console.WriteLine($"Page : {d.GetProperty("title")}");
Console.WriteLine($"Preview : {d.GetProperty("screenshot_url")}\n");
Console.WriteLine("=== AI Analysis ===");
Console.WriteLine(d.GetProperty("analysis"));
```
</Tab>
<Tab value="Rust">
```rust
println!("Page : {}", data["title"].as_str().unwrap_or(""));
println!("Preview : {}\n", data["screenshot_url"].as_str().unwrap_or(""));
println!("=== AI Analysis ===");
println!("{}", data["analysis"].as_str().unwrap_or(""));
```
</Tab>
</Tabs>
</Step>
<Step>
### Run a competitor audit across multiple pages [#run-a-competitor-audit-across-multiple-pages]
Analyze several competitor landing pages with a consistent prompt and save the results as a structured report.
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
````python
import json, time, requests
API_KEY = "YOUR_API_KEY"
PROMPT = """Analyze this landing page and return a JSON object with these keys:
- value_proposition (string)
- primary_cta (string)
- target_audience (string)
- pricing_visible (boolean)
- social_proof_types (array of strings: "testimonials", "logos", "stats", etc.)"""
COMPETITORS = [
{"name": "Stripe", "url": "https://stripe.com"},
{"name": "Paddle", "url": "https://paddle.com"},
{"name": "Lemonsqueezy", "url": "https://lemonsqueezy.com"},
]
report = []
for comp in COMPETITORS:
r = requests.get("https://api.capturekit.dev/v1/analyze",
headers={"x-api-key": API_KEY},
params={"url": comp["url"], "prompt": PROMPT})
data = r.json()
analysis_text = data.get("analysis", "{}")
try:
# AI may return the JSON wrapped in markdown fences
raw = analysis_text.strip().removeprefix("```json").removesuffix("```").strip()
analysis = json.loads(raw)
except json.JSONDecodeError:
analysis = {"raw": analysis_text}
report.append({"competitor": comp["name"], "url": comp["url"], **analysis})
print(f"✓ {comp['name']} analyzed")
time.sleep(2)
with open("competitor_audit.json", "w") as f:
json.dump(report, f, indent=2)
print("\nReport saved to competitor_audit.json")
````
</Tab>
<Tab value="TypeScript">
````typescript
import { writeFileSync } from "fs";
const API_KEY = "YOUR_API_KEY";
const PROMPT = `Analyze this landing page and return a JSON object with these keys:
- value_proposition (string)
- primary_cta (string)
- target_audience (string)
- pricing_visible (boolean)
- social_proof_types (array of strings)`;
const competitors = [
{ name: "Stripe", url: "https://stripe.com" },
{ name: "Paddle", url: "https://paddle.com" },
{ name: "Lemonsqueezy", url: "https://lemonsqueezy.com" },
];
const report: any[] = [];
for (const comp of competitors) {
const params = new URLSearchParams({ url: comp.url, prompt: PROMPT });
const res = await fetch(`https://api.capturekit.dev/v1/analyze?${params}`, {
headers: { "x-api-key": API_KEY },
});
const data = await res.json();
let analysis: any;
try {
const raw = (data.analysis ?? "{}").replace(/^```json\n?/, "").replace(/```$/, "").trim();
analysis = JSON.parse(raw);
} catch { analysis = { raw: data.analysis }; }
report.push({ competitor: comp.name, url: comp.url, ...analysis });
console.log(`✓ ${comp.name} analyzed`);
await new Promise(r => setTimeout(r, 2000));
}
writeFileSync("competitor_audit.json", JSON.stringify(report, null, 2));
console.log("\nReport saved to competitor_audit.json");
````
</Tab>
<Tab value="PHP">
````php
<?php
$apiKey = "YOUR_API_KEY";
$prompt = "Analyze this landing page and return a JSON object with keys: value_proposition, primary_cta, target_audience, pricing_visible, social_proof_types.";
$competitors = [
["name" => "Stripe", "url" => "https://stripe.com"],
["name" => "Paddle", "url" => "https://paddle.com"],
["name" => "Lemonsqueezy", "url" => "https://lemonsqueezy.com"],
];
$report = [];
foreach ($competitors as $comp) {
$params = http_build_query(["url" => $comp["url"], "prompt" => $prompt]);
$ch = curl_init("https://api.capturekit.dev/v1/analyze?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
$raw = preg_replace('/^```json\n?|```$/', '', trim($data["analysis"] ?? "{}"));
$analysis = json_decode($raw, true) ?? ["raw" => $data["analysis"]];
$report[] = array_merge(["competitor" => $comp["name"], "url" => $comp["url"]], $analysis);
echo "✓ {$comp['name']} analyzed\n";
sleep(2);
}
file_put_contents("competitor_audit.json", json_encode($report, JSON_PRETTY_PRINT));
echo "\nReport saved to competitor_audit.json\n";
````
</Tab>
<Tab value="Go">
````go
package main
import (
"encoding/json"
"fmt"
"io"
"net/http"
"net/url"
"os"
"strings"
"time"
)
const (
APIKey = "YOUR_API_KEY"
Prompt = "Analyze this landing page and return a JSON object: value_proposition, primary_cta, target_audience, pricing_visible, social_proof_types."
)
type Competitor struct{ Name, URL string }
func analyze(comp Competitor) map[string]any {
params := url.Values{"url": {comp.URL}, "prompt": {Prompt}}
req, _ := http.NewRequest("GET", "https://api.capturekit.dev/v1/analyze?"+params.Encode(), nil)
req.Header.Set("x-api-key", APIKey)
resp, _ := http.DefaultClient.Do(req)
body, _ := io.ReadAll(resp.Body)
resp.Body.Close()
var data map[string]any
json.Unmarshal(body, &data)
raw := strings.TrimSpace(fmt.Sprint(data["analysis"]))
raw = strings.TrimPrefix(raw, "```json")
raw = strings.TrimSuffix(raw, "```")
var analysis map[string]any
if err := json.Unmarshal([]byte(strings.TrimSpace(raw)), &analysis); err != nil {
analysis = map[string]any{"raw": raw}
}
analysis["competitor"] = comp.Name
analysis["url"] = comp.URL
return analysis
}
func main() {
competitors := []Competitor{
{"Stripe", "https://stripe.com"},
{"Paddle", "https://paddle.com"},
{"Lemonsqueezy", "https://lemonsqueezy.com"},
}
var report []map[string]any
for _, c := range competitors {
report = append(report, analyze(c))
fmt.Printf("✓ %s analyzed\n", c.Name)
time.Sleep(2 * time.Second)
}
b, _ := json.MarshalIndent(report, "", " ")
os.WriteFile("competitor_audit.json", b, 0644)
fmt.Println("\nReport saved to competitor_audit.json")
}
````
</Tab>
<Tab value="Java">
````java
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
import java.nio.file.*;
import java.util.*;
import org.json.*;
public class Main {
static final String API_KEY = "YOUR_API_KEY";
static final String PROMPT = "Analyze this landing page and return a JSON object: value_proposition, primary_cta, target_audience, pricing_visible, social_proof_types.";
public static void main(String[] args) throws Exception {
var client = HttpClient.newHttpClient();
var competitors = List.of(
Map.of("name","Stripe", "url","https://stripe.com"),
Map.of("name","Paddle", "url","https://paddle.com"),
Map.of("name","Lemonsqueezy", "url","https://lemonsqueezy.com"));
var report = new JSONArray();
for (var comp : competitors) {
var encodedUrl = URLEncoder.encode(comp.get("url"), StandardCharsets.UTF_8);
var encodedPrompt = URLEncoder.encode(PROMPT, StandardCharsets.UTF_8);
var req = HttpRequest.newBuilder()
.uri(URI.create("https://api.capturekit.dev/v1/analyze?url=" + encodedUrl + "&prompt=" + encodedPrompt))
.header("x-api-key", API_KEY).GET().build();
var resp = client.send(req, HttpResponse.BodyHandlers.ofString());
var data = new JSONObject(resp.body());
var analysisText = data.getString("analysis")
.replaceAll("^```json\\n?","").replaceAll("```$","").strip();
JSONObject analysis;
try { analysis = new JSONObject(analysisText); }
catch (Exception e) { analysis = new JSONObject().put("raw", analysisText); }
analysis.put("competitor", comp.get("name")).put("url", comp.get("url"));
report.put(analysis);
System.out.println("✓ " + comp.get("name") + " analyzed");
Thread.sleep(2000);
}
Files.writeString(Path.of("competitor_audit.json"), report.toString(2));
System.out.println("\nReport saved to competitor_audit.json");
}
}
````
</Tab>
<Tab value="C#">
````csharp
using System.Net.Http;
using System.Text.Json;
using System.Text.RegularExpressions;
const string API_KEY = "YOUR_API_KEY";
const string PROMPT = "Analyze this landing page and return a JSON object: value_proposition, primary_cta, target_audience, pricing_visible, social_proof_types.";
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", API_KEY);
var competitors = new[] {
(name: "Stripe", url: "https://stripe.com"),
(name: "Paddle", url: "https://paddle.com"),
(name: "Lemonsqueezy", url: "https://lemonsqueezy.com"),
};
var report = new List<object>();
foreach (var comp in competitors)
{
var encodedUrl = Uri.EscapeDataString(comp.url);
var encodedPrompt = Uri.EscapeDataString(PROMPT);
var body = await client.GetStringAsync($"https://api.capturekit.dev/v1/analyze?url={encodedUrl}&prompt={encodedPrompt}");
var data = JsonDocument.Parse(body).RootElement;
var analysisText = data.GetProperty("analysis").GetString() ?? "{}";
var clean = Regex.Replace(analysisText.Trim(), @"^```json\n?|```$", "").Trim();
object analysis;
try { analysis = JsonSerializer.Deserialize<Dictionary<string, object>>(clean)!; }
catch { analysis = new { raw = analysisText }; }
report.Add(new { competitor = comp.name, comp.url, analysis });
Console.WriteLine($"✓ {comp.name} analyzed");
await Task.Delay(2000);
}
File.WriteAllText("competitor_audit.json",
JsonSerializer.Serialize(report, new JsonSerializerOptions { WriteIndented = true }));
Console.WriteLine("\nReport saved to competitor_audit.json");
````
</Tab>
<Tab value="Rust">
````rust
use reqwest::Client;
use serde_json::{json, Value};
use std::{fs, time::Duration};
use tokio::time::sleep;
const API_KEY: &str = "YOUR_API_KEY";
const PROMPT: &str = "Analyze this landing page and return a JSON object: value_proposition, primary_cta, target_audience, pricing_visible, social_proof_types.";
#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
let client = Client::new();
let competitors = [("Stripe","https://stripe.com"), ("Paddle","https://paddle.com"), ("Lemonsqueezy","https://lemonsqueezy.com")];
let mut report = Vec::new();
for (name, url) in &competitors {
let data = client.get("https://api.capturekit.dev/v1/analyze")
.header("x-api-key", API_KEY)
.query(&[("url", url), ("prompt", &PROMPT)])
.send().await?.json::<Value>().await?;
let analysis_text = data["analysis"].as_str().unwrap_or("{}");
let clean = analysis_text.trim().trim_start_matches("```json").trim_end_matches("```").trim();
let analysis: Value = serde_json::from_str(clean).unwrap_or(json!({ "raw": analysis_text }));
report.push(json!({ "competitor": name, "url": url, "analysis": analysis }));
println!("✓ {} analyzed", name);
sleep(Duration::from_secs(2)).await;
}
fs::write("competitor_audit.json", serde_json::to_string_pretty(&report).unwrap()).unwrap();
println!("\nReport saved to competitor_audit.json");
Ok(())
}
````
</Tab>
</Tabs>
</Step>
</Steps>
<Callout type="info">
Instruct the AI to return structured JSON in your `prompt` — the model will format its output accordingly, making it easy to parse and store results in a database or spreadsheet without additional post-processing.
</Callout>
# Extract Content as Markdown (/playbooks/capturekit-content-extraction)
## Overview [#overview]
The CaptureKit content endpoint fetches a webpage, strips navigation, ads, and layout chrome, then returns the main body as **clean Markdown**. Use it for building RAG datasets, indexing documentation, or archiving articles.
## Prerequisites [#prerequisites]
* A CaptureKit API key — get one at [app.capturekit.dev](https://app.capturekit.dev)
* Install dependencies for your language:
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```bash
pip install requests
```
</Tab>
<Tab value="TypeScript">
No extra dependencies — uses the native `fetch` API (Node 18+).
</Tab>
<Tab value="PHP">
`curl` extension enabled (on by default).
</Tab>
<Tab value="Go">
No extra dependencies — uses `net/http` (Go 1.18+).
</Tab>
<Tab value="Java">
No extra dependencies — uses `java.net.http` (Java 11+).
</Tab>
<Tab value="C#">
No extra dependencies — uses `System.Net.Http` (.NET 6+).
</Tab>
<Tab value="Rust">
```toml
# Cargo.toml
[dependencies]
reqwest = { version = "0.12", features = ["json"] }
tokio = { version = "1", features = ["full"] }
serde_json = "1"
```
</Tab>
</Tabs>
## Steps [#steps]
<Steps>
<Step>
### Fetch the page content [#fetch-the-page-content]
Call `GET /v1/content` with the `url` parameter.
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```python
import requests
API_KEY = "YOUR_API_KEY"
response = requests.get(
"https://api.capturekit.dev/v1/content",
headers={"x-api-key": API_KEY},
params={"url": "https://stripe.com/docs/payments"},
)
data = response.json()
print(data)
```
</Tab>
<Tab value="TypeScript">
```typescript
const API_KEY = "YOUR_API_KEY";
const params = new URLSearchParams({ url: "https://stripe.com/docs/payments" });
const response = await fetch(`https://api.capturekit.dev/v1/content?${params}`, {
headers: { "x-api-key": API_KEY },
});
const data = await response.json();
console.log(data);
```
</Tab>
<Tab value="PHP">
```php
<?php
$apiKey = "YOUR_API_KEY";
$params = http_build_query(["url" => "https://stripe.com/docs/payments"]);
$ch = curl_init("https://api.capturekit.dev/v1/content?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($data);
```
</Tab>
<Tab value="Go">
```go
package main
import (
"encoding/json"
"fmt"
"io"
"net/http"
"net/url"
)
func main() {
params := url.Values{"url": {"https://stripe.com/docs/payments"}}
req, _ := http.NewRequest("GET", "https://api.capturekit.dev/v1/content?"+params.Encode(), nil)
req.Header.Set("x-api-key", "YOUR_API_KEY")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var data map[string]any
json.Unmarshal(body, &data)
fmt.Println(data)
}
```
</Tab>
<Tab value="Java">
```java
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
var client = HttpClient.newHttpClient();
var target = URLEncoder.encode("https://stripe.com/docs/payments", StandardCharsets.UTF_8);
var request = HttpRequest.newBuilder()
.uri(URI.create("https://api.capturekit.dev/v1/content?url=" + target))
.header("x-api-key", "YOUR_API_KEY").GET().build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```
</Tab>
<Tab value="C#">
```csharp
using System.Net.Http;
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");
var target = Uri.EscapeDataString("https://stripe.com/docs/payments");
var body = await client.GetStringAsync($"https://api.capturekit.dev/v1/content?url={target}");
Console.WriteLine(body);
```
</Tab>
<Tab value="Rust">
```rust
#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
let data = reqwest::Client::new()
.get("https://api.capturekit.dev/v1/content")
.header("x-api-key", "YOUR_API_KEY")
.query(&[("url", "https://stripe.com/docs/payments")])
.send().await?.json::<serde_json::Value>().await?;
println!("{:#?}", data);
Ok(())
}
```
</Tab>
</Tabs>
</Step>
<Step>
### Access the Markdown content [#access-the-markdown-content]
The response includes `markdown`, `title`, `description`, `author`, `published_at`, and `word_count`.
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```python
print(f"Title : {data.get('title')}")
print(f"Author : {data.get('author', 'N/A')}")
print(f"Word count : {data.get('word_count')} words")
print()
print("--- Markdown preview ---")
markdown = data.get("markdown", "")
print(markdown[:1000])
```
</Tab>
<Tab value="TypeScript">
```typescript
console.log(`Title : ${data.title}`);
console.log(`Author : ${data.author ?? "N/A"}`);
console.log(`Word count : ${data.word_count} words\n`);
console.log("--- Markdown preview ---");
console.log(data.markdown?.slice(0, 1000));
```
</Tab>
<Tab value="PHP">
```php
echo "Title : {$data['title']}\n";
echo "Author : " . ($data["author"] ?? "N/A") . "\n";
echo "Word count : {$data['word_count']} words\n\n";
echo "--- Markdown preview ---\n";
echo substr($data["markdown"] ?? "", 0, 1000) . "\n";
```
</Tab>
<Tab value="Go">
```go
fmt.Printf("Title : %v\nAuthor : %v\nWord count : %v words\n\n",
data["title"], data["author"], data["word_count"])
markdown := data["markdown"].(string)
if len(markdown) > 1000 { markdown = markdown[:1000] }
fmt.Println("--- Markdown preview ---\n" + markdown)
```
</Tab>
<Tab value="Java">
```java
import org.json.*;
var d = new JSONObject(response.body());
var markdown = d.getString("markdown");
System.out.printf("Title : %s%nAuthor : %s%nWord count : %d words%n%n",
d.getString("title"), d.optString("author", "N/A"), d.getInt("word_count"));
System.out.println("--- Markdown preview ---");
System.out.println(markdown.substring(0, Math.min(1000, markdown.length())));
```
</Tab>
<Tab value="C#">
```csharp
using System.Text.Json;
var d = JsonDocument.Parse(body).RootElement;
var markdown = d.GetProperty("markdown").GetString() ?? "";
Console.WriteLine($"Title : {d.GetProperty("title")}");
Console.WriteLine($"Author : {(d.TryGetProperty("author", out var a) ? a : (object)"N/A")}");
Console.WriteLine($"Word count : {d.GetProperty("word_count")} words\n");
Console.WriteLine("--- Markdown preview ---");
Console.WriteLine(markdown[..Math.Min(1000, markdown.Length)]);
```
</Tab>
<Tab value="Rust">
```rust
let markdown = data["markdown"].as_str().unwrap_or("");
println!("Title : {}", data["title"].as_str().unwrap_or(""));
println!("Author : {}", data["author"].as_str().unwrap_or("N/A"));
println!("Word count : {} words\n", data["word_count"]);
println!("--- Markdown preview ---");
println!("{}", &markdown[..1000.min(markdown.len())]);
```
</Tab>
</Tabs>
</Step>
<Step>
### Crawl and archive a list of documentation pages [#crawl-and-archive-a-list-of-documentation-pages]
Fetch and save multiple pages as Markdown files for offline search or RAG ingestion.
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```python
import os, time, requests
API_KEY = "YOUR_API_KEY"
os.makedirs("docs_archive", exist_ok=True)
PAGES = [
"https://stripe.com/docs/payments",
"https://stripe.com/docs/billing",
"https://stripe.com/docs/connect",
]
for page_url in PAGES:
r = requests.get("https://api.capturekit.dev/v1/content",
headers={"x-api-key": API_KEY}, params={"url": page_url})
data = r.json()
slug = page_url.rstrip("/").split("/")[-1]
path = f"docs_archive/{slug}.md"
with open(path, "w") as f:
f.write(f"# {data.get('title', slug)}\n\n")
f.write(data.get("markdown", ""))
print(f"Saved: {path} ({data.get('word_count', 0)} words)")
time.sleep(1)
print("Done!")
```
</Tab>
<Tab value="TypeScript">
```typescript
import { mkdirSync, writeFileSync } from "fs";
const API_KEY = "YOUR_API_KEY";
mkdirSync("docs_archive", { recursive: true });
const PAGES = [
"https://stripe.com/docs/payments",
"https://stripe.com/docs/billing",
"https://stripe.com/docs/connect",
];
for (const pageUrl of PAGES) {
const params = new URLSearchParams({ url: pageUrl });
const res = await fetch(`https://api.capturekit.dev/v1/content?${params}`, {
headers: { "x-api-key": API_KEY },
});
const data = await res.json();
const slug = pageUrl.replace(/\/$/, "").split("/").at(-1)!;
writeFileSync(`docs_archive/${slug}.md`, `# ${data.title ?? slug}\n\n${data.markdown ?? ""}`);
console.log(`Saved: docs_archive/${slug}.md (${data.word_count ?? 0} words)`);
await new Promise(r => setTimeout(r, 1000));
}
console.log("Done!");
```
</Tab>
<Tab value="PHP">
```php
<?php
$apiKey = "YOUR_API_KEY";
@mkdir("docs_archive");
$pages = [
"https://stripe.com/docs/payments",
"https://stripe.com/docs/billing",
"https://stripe.com/docs/connect",
];
foreach ($pages as $pageUrl) {
$params = http_build_query(["url" => $pageUrl]);
$ch = curl_init("https://api.capturekit.dev/v1/content?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
$slug = basename(rtrim($pageUrl, "/"));
$path = "docs_archive/{$slug}.md";
file_put_contents($path, "# {$data['title']}\n\n{$data['markdown']}");
echo "Saved: {$path} ({$data['word_count']} words)\n";
sleep(1);
}
echo "Done!\n";
```
</Tab>
<Tab value="Go">
```go
package main
import (
"encoding/json"
"fmt"
"io"
"net/http"
"net/url"
"os"
"path/filepath"
"strings"
"time"
)
func main() {
os.MkdirAll("docs_archive", 0755)
apiKey := "YOUR_API_KEY"
pages := []string{
"https://stripe.com/docs/payments",
"https://stripe.com/docs/billing",
"https://stripe.com/docs/connect",
}
for _, pageURL := range pages {
params := url.Values{"url": {pageURL}}
req, _ := http.NewRequest("GET", "https://api.capturekit.dev/v1/content?"+params.Encode(), nil)
req.Header.Set("x-api-key", apiKey)
resp, _ := http.DefaultClient.Do(req)
body, _ := io.ReadAll(resp.Body)
resp.Body.Close()
var data map[string]any
json.Unmarshal(body, &data)
parts := strings.Split(strings.TrimRight(pageURL, "/"), "/")
slug := parts[len(parts)-1]
path := filepath.Join("docs_archive", slug+".md")
content := fmt.Sprintf("# %v\n\n%v", data["title"], data["markdown"])
os.WriteFile(path, []byte(content), 0644)
fmt.Printf("Saved: %s (%.0f words)\n", path, data["word_count"])
time.Sleep(time.Second)
}
fmt.Println("Done!")
}
```
</Tab>
<Tab value="Java">
```java
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
import java.nio.file.*;
import java.util.List;
import org.json.*;
public class Main {
public static void main(String[] args) throws Exception {
var client = HttpClient.newHttpClient();
var apiKey = "YOUR_API_KEY";
Files.createDirectories(Path.of("docs_archive"));
var pages = List.of(
"https://stripe.com/docs/payments",
"https://stripe.com/docs/billing",
"https://stripe.com/docs/connect");
for (var pageUrl : pages) {
var encoded = URLEncoder.encode(pageUrl, StandardCharsets.UTF_8);
var req = HttpRequest.newBuilder()
.uri(URI.create("https://api.capturekit.dev/v1/content?url=" + encoded))
.header("x-api-key", apiKey).GET().build();
var resp = client.send(req, HttpResponse.BodyHandlers.ofString());
var data = new JSONObject(resp.body());
var slug = pageUrl.replaceAll("/$","").replaceAll(".*/","");
var content = "# " + data.getString("title") + "\n\n" + data.getString("markdown");
Files.writeString(Path.of("docs_archive/" + slug + ".md"), content);
System.out.printf("Saved: docs_archive/%s.md (%d words)%n", slug, data.getInt("word_count"));
Thread.sleep(1000);
}
System.out.println("Done!");
}
}
```
</Tab>
<Tab value="C#">
```csharp
using System.Net.Http;
using System.Text.Json;
var apiKey = "YOUR_API_KEY";
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", apiKey);
Directory.CreateDirectory("docs_archive");
var pages = new[]
{
"https://stripe.com/docs/payments",
"https://stripe.com/docs/billing",
"https://stripe.com/docs/connect",
};
foreach (var pageUrl in pages)
{
var encoded = Uri.EscapeDataString(pageUrl);
var body = await client.GetStringAsync($"https://api.capturekit.dev/v1/content?url={encoded}");
var data = JsonDocument.Parse(body).RootElement;
var slug = pageUrl.TrimEnd('/').Split('/').Last();
var content = $"# {data.GetProperty("title")}\n\n{data.GetProperty("markdown")}";
File.WriteAllText($"docs_archive/{slug}.md", content);
Console.WriteLine($"Saved: docs_archive/{slug}.md ({data.GetProperty("word_count")} words)");
await Task.Delay(1000);
}
Console.WriteLine("Done!");
```
</Tab>
<Tab value="Rust">
```rust
use reqwest::Client;
use serde_json::Value;
use std::{fs, path::Path, time::Duration};
use tokio::time::sleep;
#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
let client = Client::new();
let api_key = "YOUR_API_KEY";
let pages = ["https://stripe.com/docs/payments", "https://stripe.com/docs/billing", "https://stripe.com/docs/connect"];
fs::create_dir_all("docs_archive").unwrap();
for page_url in &pages {
let data = client.get("https://api.capturekit.dev/v1/content")
.header("x-api-key", api_key)
.query(&[("url", page_url)])
.send().await?.json::<Value>().await?;
let slug = page_url.trim_end_matches('/').split('/').last().unwrap_or("page");
let path = format!("docs_archive/{}.md", slug);
let content = format!("# {}\n\n{}", data["title"].as_str().unwrap_or(""), data["markdown"].as_str().unwrap_or(""));
fs::write(&path, content).unwrap();
println!("Saved: {} ({} words)", path, data["word_count"]);
sleep(Duration::from_secs(1)).await;
}
println!("Done!");
Ok(())
}
```
</Tab>
</Tabs>
</Step>
</Steps>
<Callout type="info">
The extracted Markdown is ideal as context chunks for a RAG (Retrieval-Augmented Generation) pipeline. Chunk by headings and embed with your preferred vector store for semantic search over any website's documentation.
</Callout>
# Screenshot a Webpage (/playbooks/capturekit-screenshot)
## Overview [#overview]
This playbook shows how to take a screenshot of any public URL and save it to disk. A common use case is **visual regression testing** or generating OG image thumbnails for a link-preview service.
## Prerequisites [#prerequisites]
* A CaptureKit API key — get one at [app.capturekit.dev](https://app.capturekit.dev)
* Install dependencies for your language:
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```bash
pip install requests
```
</Tab>
<Tab value="TypeScript">
No extra dependencies — uses the native `fetch` API (Node 18+).
</Tab>
<Tab value="PHP">
`curl` extension enabled (on by default).
</Tab>
<Tab value="Go">
No extra dependencies — uses `net/http` (Go 1.18+).
</Tab>
<Tab value="Java">
No extra dependencies — uses `java.net.http` (Java 11+).
</Tab>
<Tab value="C#">
No extra dependencies — uses `System.Net.Http` (.NET 6+).
</Tab>
<Tab value="Rust">
```toml
# Cargo.toml
[dependencies]
reqwest = { version = "0.12", features = ["json"] }
tokio = { version = "1", features = ["full"] }
serde_json = "1"
```
</Tab>
</Tabs>
## Steps [#steps]
<Steps>
<Step>
### Request a screenshot [#request-a-screenshot]
Call `GET /v1/capture` with the `url` parameter. Additional options control the viewport, format, and full-page capture.
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```python
import requests
API_KEY = "YOUR_API_KEY"
response = requests.get(
"https://api.capturekit.dev/v1/capture",
headers={"x-api-key": API_KEY},
params={
"url": "https://stripe.com",
"format": "png",
"full_page": "true",
"width": "1440",
"height": "900",
},
)
data = response.json()
print(data)
```
</Tab>
<Tab value="TypeScript">
```typescript
const API_KEY = "YOUR_API_KEY";
const params = new URLSearchParams({
url: "https://stripe.com",
format: "png",
full_page: "true",
width: "1440",
height: "900",
});
const response = await fetch(`https://api.capturekit.dev/v1/capture?${params}`, {
headers: { "x-api-key": API_KEY },
});
const data = await response.json();
console.log(data);
```
</Tab>
<Tab value="PHP">
```php
<?php
$apiKey = "YOUR_API_KEY";
$params = http_build_query([
"url" => "https://stripe.com",
"format" => "png",
"full_page" => "true",
"width" => "1440",
"height" => "900",
]);
$ch = curl_init("https://api.capturekit.dev/v1/capture?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($data);
```
</Tab>
<Tab value="Go">
```go
package main
import (
"encoding/json"
"fmt"
"io"
"net/http"
"net/url"
)
func main() {
params := url.Values{
"url": {"https://stripe.com"}, "format": {"png"},
"full_page": {"true"}, "width": {"1440"}, "height": {"900"},
}
req, _ := http.NewRequest("GET", "https://api.capturekit.dev/v1/capture?"+params.Encode(), nil)
req.Header.Set("x-api-key", "YOUR_API_KEY")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var data map[string]any
json.Unmarshal(body, &data)
fmt.Println(data)
}
```
</Tab>
<Tab value="Java">
```java
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
var apiKey = "YOUR_API_KEY";
var target = URLEncoder.encode("https://stripe.com", StandardCharsets.UTF_8);
var url = "https://api.capturekit.dev/v1/capture?url=" + target + "&format=png&full_page=true&width=1440&height=900";
var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder().uri(URI.create(url))
.header("x-api-key", apiKey).GET().build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```
</Tab>
<Tab value="C#">
```csharp
using System.Net.Http;
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");
var target = Uri.EscapeDataString("https://stripe.com");
var body = await client.GetStringAsync(
$"https://api.capturekit.dev/v1/capture?url={target}&format=png&full_page=true&width=1440&height=900");
Console.WriteLine(body);
```
</Tab>
<Tab value="Rust">
```rust
#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
let data = reqwest::Client::new()
.get("https://api.capturekit.dev/v1/capture")
.header("x-api-key", "YOUR_API_KEY")
.query(&[("url", "https://stripe.com"), ("format", "png"), ("full_page", "true"), ("width", "1440"), ("height", "900")])
.send().await?.json::<serde_json::Value>().await?;
println!("{:#?}", data);
Ok(())
}
```
</Tab>
</Tabs>
</Step>
<Step>
### Get the image URL from the response [#get-the-image-url-from-the-response]
The API returns a `screenshot_url` with the hosted image — or a base64-encoded `image` field if you set `response_type=base64`.
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```python
screenshot_url = data.get("screenshot_url")
print(f"Screenshot ready: {screenshot_url}")
```
</Tab>
<Tab value="TypeScript">
```typescript
const { screenshot_url } = data;
console.log(`Screenshot ready: ${screenshot_url}`);
```
</Tab>
<Tab value="PHP">
```php
$screenshotUrl = $data["screenshot_url"] ?? "";
echo "Screenshot ready: {$screenshotUrl}\n";
```
</Tab>
<Tab value="Go">
```go
screenshotURL := data["screenshot_url"].(string)
fmt.Println("Screenshot ready:", screenshotURL)
```
</Tab>
<Tab value="Java">
```java
import org.json.*;
var screenshotUrl = new JSONObject(response.body()).getString("screenshot_url");
System.out.println("Screenshot ready: " + screenshotUrl);
```
</Tab>
<Tab value="C#">
```csharp
using System.Text.Json;
var screenshotUrl = JsonDocument.Parse(body).RootElement.GetProperty("screenshot_url").GetString();
Console.WriteLine($"Screenshot ready: {screenshotUrl}");
```
</Tab>
<Tab value="Rust">
```rust
let screenshot_url = data["screenshot_url"].as_str().unwrap_or("");
println!("Screenshot ready: {}", screenshot_url);
```
</Tab>
</Tabs>
</Step>
<Step>
### Download and save the image [#download-and-save-the-image]
Fetch the image bytes from the URL and write them to disk.
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```python
filename = "screenshot.png"
with requests.get(screenshot_url, stream=True) as r:
r.raise_for_status()
with open(filename, "wb") as f:
for chunk in r.iter_content(chunk_size=8192):
f.write(chunk)
print(f"Saved to {filename}")
```
</Tab>
<Tab value="TypeScript">
```typescript
import { writeFileSync } from "fs";
const imgResponse = await fetch(screenshotUrl);
const buffer = Buffer.from(await imgResponse.arrayBuffer());
writeFileSync("screenshot.png", buffer);
console.log("Saved to screenshot.png");
```
</Tab>
<Tab value="PHP">
```php
$fp = fopen("screenshot.png", "wb");
$ch = curl_init($screenshotUrl);
curl_setopt($ch, CURLOPT_FILE, $fp);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
curl_exec($ch);
curl_close($ch);
fclose($fp);
echo "Saved to screenshot.png\n";
```
</Tab>
<Tab value="Go">
```go
import "os"
resp, _ := http.Get(screenshotURL)
defer resp.Body.Close()
file, _ := os.Create("screenshot.png")
defer file.Close()
io.Copy(file, resp.Body)
fmt.Println("Saved to screenshot.png")
```
</Tab>
<Tab value="Java">
```java
import java.net.URL;
import java.nio.file.*;
Files.copy(new URL(screenshotUrl).openStream(), Path.of("screenshot.png"), StandardCopyOption.REPLACE_EXISTING);
System.out.println("Saved to screenshot.png");
```
</Tab>
<Tab value="C#">
```csharp
var imageBytes = await new HttpClient().GetByteArrayAsync(screenshotUrl);
File.WriteAllBytes("screenshot.png", imageBytes);
Console.WriteLine("Saved to screenshot.png");
```
</Tab>
<Tab value="Rust">
```rust
use std::{fs::File, io::Write};
let bytes = reqwest::get(screenshot_url).await?.bytes().await?;
let mut file = File::create("screenshot.png").unwrap();
file.write_all(&bytes).unwrap();
println!("Saved to screenshot.png");
```
</Tab>
</Tabs>
</Step>
</Steps>
<Callout type="info">
Use `full_page=false` to capture only the above-the-fold viewport — ideal for social media preview thumbnails where a fixed-height 630×1200 px crop is required.
</Callout>
# Extract Audio from a Video (/playbooks/huntapi-audio-download)
## Overview [#overview]
By passing `quality: "audio"` to the HuntAPI downloader, you get an MP3 extract instead of the full video. This playbook builds a complete audio extraction pipeline including job submission, polling, and saving.
## Prerequisites [#prerequisites]
* A HuntAPI key — get one at [app.huntapi.com](https://app.huntapi.com)
* Install dependencies for your language:
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```bash
pip install requests
```
</Tab>
<Tab value="TypeScript">
No extra dependencies — uses the native `fetch` API (Node 18+).
</Tab>
<Tab value="PHP">
`curl` extension enabled (on by default).
</Tab>
<Tab value="Go">
No extra dependencies — uses `net/http` (Go 1.18+).
</Tab>
<Tab value="Java">
No extra dependencies — uses `java.net.http` (Java 11+).
</Tab>
<Tab value="C#">
No extra dependencies — uses `System.Net.Http` (.NET 6+).
</Tab>
<Tab value="Rust">
```toml
# Cargo.toml
[dependencies]
reqwest = { version = "0.12", features = ["json"] }
tokio = { version = "1", features = ["full"] }
serde_json = "1"
```
</Tab>
</Tabs>
## Steps [#steps]
<Steps>
<Step>
### Submit an audio extraction job [#submit-an-audio-extraction-job]
Use the same `/v1/video/download` endpoint with `quality=audio`.
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```python
import requests
API_KEY = "YOUR_API_KEY"
VIDEO_URL = "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
response = requests.get(
"https://api.huntapi.com/v1/video/download",
headers={"x-api-key": API_KEY},
params={"url": VIDEO_URL, "quality": "audio"},
)
data = response.json()
job_id = data["job_id"]
print(f"Audio job submitted: {job_id}")
```
</Tab>
<Tab value="TypeScript">
```typescript
const API_KEY = "YOUR_API_KEY";
const VIDEO_URL = "https://www.youtube.com/watch?v=dQw4w9WgXcQ";
const params = new URLSearchParams({ url: VIDEO_URL, quality: "audio" });
const response = await fetch(`https://api.huntapi.com/v1/video/download?${params}`, {
headers: { "x-api-key": API_KEY },
});
const { job_id } = await response.json();
console.log(`Audio job submitted: ${job_id}`);
```
</Tab>
<Tab value="PHP">
```php
<?php
$apiKey = "YOUR_API_KEY";
$videoUrl = "https://www.youtube.com/watch?v=dQw4w9WgXcQ";
$params = http_build_query(["url" => $videoUrl, "quality" => "audio"]);
$ch = curl_init("https://api.huntapi.com/v1/video/download?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
$jobId = $data["job_id"];
echo "Audio job submitted: {$jobId}\n";
```
</Tab>
<Tab value="Go">
```go
package main
import (
"encoding/json"
"fmt"
"io"
"net/http"
"net/url"
"os"
"time"
)
const (
APIKey = "YOUR_API_KEY"
VideoURL = "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
)
func get(apiKey, rawURL string) map[string]any {
req, _ := http.NewRequest("GET", rawURL, nil)
req.Header.Set("x-api-key", apiKey)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var m map[string]any
json.Unmarshal(body, &m)
return m
}
func main() {
params := url.Values{"url": {VideoURL}, "quality": {"audio"}}
data := get(APIKey, "https://api.huntapi.com/v1/video/download?"+params.Encode())
jobID := data["job_id"].(string)
fmt.Println("Audio job submitted:", jobID)
// polling in next step...
}
```
</Tab>
<Tab value="Java">
```java
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
import org.json.*;
var apiKey = "YOUR_API_KEY";
var videoUrl = URLEncoder.encode("https://www.youtube.com/watch?v=dQw4w9WgXcQ", StandardCharsets.UTF_8);
var client = HttpClient.newHttpClient();
var req = HttpRequest.newBuilder()
.uri(URI.create("https://api.huntapi.com/v1/video/download?url=" + videoUrl + "&quality=audio"))
.header("x-api-key", apiKey).GET().build();
var resp = client.send(req, HttpResponse.BodyHandlers.ofString());
var jobId = new JSONObject(resp.body()).getString("job_id");
System.out.println("Audio job submitted: " + jobId);
```
</Tab>
<Tab value="C#">
```csharp
using System.Net.Http;
using System.Text.Json;
var apiKey = "YOUR_API_KEY";
var videoUrl = Uri.EscapeDataString("https://www.youtube.com/watch?v=dQw4w9WgXcQ");
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", apiKey);
var body = await client.GetStringAsync($"https://api.huntapi.com/v1/video/download?url={videoUrl}&quality=audio");
var jobId = JsonDocument.Parse(body).RootElement.GetProperty("job_id").GetString()!;
Console.WriteLine($"Audio job submitted: {jobId}");
```
</Tab>
<Tab value="Rust">
```rust
use reqwest::Client;
use serde_json::Value;
#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
let client = Client::new();
let api_key = "YOUR_API_KEY";
let video_url = "https://www.youtube.com/watch?v=dQw4w9WgXcQ";
let data = client.get("https://api.huntapi.com/v1/video/download")
.header("x-api-key", api_key)
.query(&[("url", video_url), ("quality", "audio")])
.send().await?.json::<Value>().await?;
let job_id = data["job_id"].as_str().unwrap();
println!("Audio job submitted: {}", job_id);
Ok(())
}
```
</Tab>
</Tabs>
</Step>
<Step>
### Poll for completion [#poll-for-completion]
Check the job status every 5 seconds until `status == "done"`.
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```python
import time
def wait_for_job(job_id: str) -> dict:
for _ in range(60):
r = requests.get(f"https://api.huntapi.com/v1/job/{job_id}",
headers={"x-api-key": API_KEY})
result = r.json()
status = result["status"]
print(f" [{status}]")
if status == "done":
return result
if status == "error":
raise RuntimeError(result.get("error", "Unknown error"))
time.sleep(5)
raise TimeoutError("Job timed out")
result = wait_for_job(job_id)
download_url = result["download_url"]
```
</Tab>
<Tab value="TypeScript">
```typescript
async function waitForJob(jobId: string) {
for (let i = 0; i < 60; i++) {
const res = await fetch(`https://api.huntapi.com/v1/job/${jobId}`, {
headers: { "x-api-key": API_KEY },
});
const result = await res.json();
console.log(` [${result.status}]`);
if (result.status === "done") return result;
if (result.status === "error") throw new Error(result.error ?? "Unknown error");
await new Promise(r => setTimeout(r, 5000));
}
throw new Error("Timeout");
}
const result = await waitForJob(job_id);
const downloadUrl = result.download_url;
```
</Tab>
<Tab value="PHP">
```php
function waitForJob(string $apiKey, string $jobId): array {
for ($i = 0; $i < 60; $i++) {
$ch = curl_init("https://api.huntapi.com/v1/job/{$jobId}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
$status = $result["status"] ?? "";
echo " [{$status}]\n";
if ($status === "done") return $result;
if ($status === "error") throw new RuntimeException($result["error"] ?? "Unknown");
sleep(5);
}
throw new RuntimeException("Timeout");
}
$result = waitForJob($apiKey, $jobId);
$downloadUrl = $result["download_url"];
```
</Tab>
<Tab value="Go">
```go
func waitForJob(apiKey, jobID string) string {
for i := 0; i < 60; i++ {
data := get(apiKey, "https://api.huntapi.com/v1/job/"+jobID)
status := data["status"].(string)
fmt.Printf(" [%s]\n", status)
if status == "done" { return data["download_url"].(string) }
if status == "error" { panic("Job failed: " + fmt.Sprint(data["error"])) }
time.Sleep(5 * time.Second)
}
panic("Timeout")
}
downloadURL := waitForJob(APIKey, jobID)
```
</Tab>
<Tab value="Java">
```java
static String waitForJob(HttpClient client, String apiKey, String jobId) throws Exception {
for (int i = 0; i < 60; i++) {
var req = HttpRequest.newBuilder()
.uri(URI.create("https://api.huntapi.com/v1/job/" + jobId))
.header("x-api-key", apiKey).GET().build();
var resp = client.send(req, HttpResponse.BodyHandlers.ofString());
var result = new JSONObject(resp.body());
var status = result.getString("status");
System.out.println(" [" + status + "]");
if ("done".equals(status)) return result.getString("download_url");
if ("error".equals(status)) throw new RuntimeException(result.optString("error"));
Thread.sleep(5000);
}
throw new RuntimeException("Timeout");
}
var downloadUrl = waitForJob(client, apiKey, jobId);
```
</Tab>
<Tab value="C#">
```csharp
async Task<string> WaitForJob(HttpClient client, string jobId)
{
for (int i = 0; i < 60; i++)
{
var body = await client.GetStringAsync($"https://api.huntapi.com/v1/job/{jobId}");
var result = JsonDocument.Parse(body).RootElement;
var status = result.GetProperty("status").GetString();
Console.WriteLine($" [{status}]");
if (status == "done") return result.GetProperty("download_url").GetString()!;
if (status == "error") throw new Exception(result.GetProperty("error").GetString());
await Task.Delay(5000);
}
throw new TimeoutException();
}
var downloadUrl = await WaitForJob(client, jobId);
```
</Tab>
<Tab value="Rust">
```rust
use tokio::time::{sleep, Duration};
async fn wait_for_job(client: &Client, api_key: &str, job_id: &str) -> String {
for _ in 0..60 {
let result = client.get(format!("https://api.huntapi.com/v1/job/{}", job_id))
.header("x-api-key", api_key)
.send().await.unwrap().json::<Value>().await.unwrap();
let status = result["status"].as_str().unwrap_or("");
println!(" [{}]", status);
if status == "done" { return result["download_url"].as_str().unwrap().to_string(); }
if status == "error" { panic!("Job failed: {}", result["error"]); }
sleep(Duration::from_secs(5)).await;
}
panic!("Timeout")
}
```
</Tab>
</Tabs>
</Step>
<Step>
### Save the audio file [#save-the-audio-file]
Download the MP3 and save it to disk.
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```python
output_file = "audio.mp3"
with requests.get(download_url, stream=True) as r:
r.raise_for_status()
with open(output_file, "wb") as f:
for chunk in r.iter_content(chunk_size=8192):
f.write(chunk)
print(f"Audio saved to {output_file} ({os.path.getsize(output_file) // 1024} KB)")
```
</Tab>
<Tab value="TypeScript">
```typescript
import { createWriteStream } from "fs";
import { Readable } from "stream";
const fileRes = await fetch(downloadUrl);
const writer = createWriteStream("audio.mp3");
Readable.fromWeb(fileRes.body as any).pipe(writer);
await new Promise((resolve, reject) => { writer.on("finish", resolve); writer.on("error", reject); });
console.log("Audio saved to audio.mp3");
```
</Tab>
<Tab value="PHP">
```php
$fp = fopen("audio.mp3", "wb");
$ch = curl_init($downloadUrl);
curl_setopt($ch, CURLOPT_FILE, $fp);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
curl_exec($ch);
curl_close($ch);
fclose($fp);
echo "Audio saved to audio.mp3\n";
```
</Tab>
<Tab value="Go">
```go
resp, _ := http.Get(downloadURL)
defer resp.Body.Close()
file, _ := os.Create("audio.mp3")
defer file.Close()
io.Copy(file, resp.Body)
fmt.Println("Audio saved to audio.mp3")
```
</Tab>
<Tab value="Java">
```java
import java.net.URL;
import java.nio.file.*;
Files.copy(new URL(downloadUrl).openStream(), Path.of("audio.mp3"), StandardCopyOption.REPLACE_EXISTING);
System.out.println("Audio saved to audio.mp3");
```
</Tab>
<Tab value="C#">
```csharp
using var audioStream = await new HttpClient().GetStreamAsync(downloadUrl);
using var file = File.Create("audio.mp3");
await audioStream.CopyToAsync(file);
Console.WriteLine("Audio saved to audio.mp3");
```
</Tab>
<Tab value="Rust">
```rust
use std::{fs::File, io::Write};
let bytes = reqwest::get(download_url).await?.bytes().await?;
let mut file = File::create("audio.mp3").unwrap();
file.write_all(&bytes).unwrap();
println!("Audio saved to audio.mp3");
```
</Tab>
</Tabs>
</Step>
</Steps>
<Callout type="info">
The extracted audio is delivered as an MP3. You can pipe it directly to a transcription service (e.g. OpenAI Whisper or Deepgram) for automatic subtitling or search indexing.
</Callout>
# Download Your First Video (/playbooks/huntapi-video-download)
## Overview [#overview]
HuntAPI uses an **asynchronous job model**: you submit a URL, receive a `job_id`, then poll until the video is ready. This playbook walks through all three steps and downloads the finished file to disk.
## Prerequisites [#prerequisites]
* A HuntAPI key — get one at [app.huntapi.com](https://app.huntapi.com)
* Install dependencies for your language:
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```bash
pip install requests
```
</Tab>
<Tab value="TypeScript">
No extra dependencies — uses the native `fetch` API (Node 18+).
</Tab>
<Tab value="PHP">
`curl` extension enabled (on by default).
</Tab>
<Tab value="Go">
No extra dependencies — uses `net/http` (Go 1.18+).
</Tab>
<Tab value="Java">
No extra dependencies — uses `java.net.http` (Java 11+).
</Tab>
<Tab value="C#">
No extra dependencies — uses `System.Net.Http` (.NET 6+).
</Tab>
<Tab value="Rust">
```toml
# Cargo.toml
[dependencies]
reqwest = { version = "0.12", features = ["json", "stream"] }
tokio = { version = "1", features = ["full"] }
serde_json = "1"
```
</Tab>
</Tabs>
## Steps [#steps]
<Steps>
<Step>
### Submit the download job [#submit-the-download-job]
Call `GET /v1/video/download` with the `url` parameter. The response immediately returns a `job_id`.
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```python
import requests
API_KEY = "YOUR_API_KEY"
VIDEO_URL = "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
response = requests.get(
"https://api.huntapi.com/v1/video/download",
headers={"x-api-key": API_KEY},
params={"url": VIDEO_URL, "quality": "best"},
)
data = response.json()
job_id = data["job_id"]
print(f"Job submitted: {job_id}")
```
</Tab>
<Tab value="TypeScript">
```typescript
const API_KEY = "YOUR_API_KEY";
const VIDEO_URL = "https://www.youtube.com/watch?v=dQw4w9WgXcQ";
const params = new URLSearchParams({ url: VIDEO_URL, quality: "best" });
const response = await fetch(`https://api.huntapi.com/v1/video/download?${params}`, {
headers: { "x-api-key": API_KEY },
});
const data = await response.json();
const jobId = data.job_id;
console.log(`Job submitted: ${jobId}`);
```
</Tab>
<Tab value="PHP">
```php
<?php
$apiKey = "YOUR_API_KEY";
$videoUrl = "https://www.youtube.com/watch?v=dQw4w9WgXcQ";
$params = http_build_query(["url" => $videoUrl, "quality" => "best"]);
$ch = curl_init("https://api.huntapi.com/v1/video/download?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
$jobId = $data["job_id"];
echo "Job submitted: {$jobId}\n";
```
</Tab>
<Tab value="Go">
```go
package main
import (
"encoding/json"
"fmt"
"io"
"net/http"
"net/url"
)
const APIKey = "YOUR_API_KEY"
const VideoURL = "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
func main() {
params := url.Values{"url": {VideoURL}, "quality": {"best"}}
req, _ := http.NewRequest("GET", "https://api.huntapi.com/v1/video/download?"+params.Encode(), nil)
req.Header.Set("x-api-key", APIKey)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var data map[string]any
json.Unmarshal(body, &data)
jobID := data["job_id"].(string)
fmt.Println("Job submitted:", jobID)
// continue in next step...
}
```
</Tab>
<Tab value="Java">
```java
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
import org.json.*;
var apiKey = "YOUR_API_KEY";
var videoUrl = URLEncoder.encode("https://www.youtube.com/watch?v=dQw4w9WgXcQ", StandardCharsets.UTF_8);
var url = "https://api.huntapi.com/v1/video/download?url=" + videoUrl + "&quality=best";
var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder().uri(URI.create(url))
.header("x-api-key", apiKey).GET().build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
var jobId = new JSONObject(response.body()).getString("job_id");
System.out.println("Job submitted: " + jobId);
```
</Tab>
<Tab value="C#">
```csharp
using System.Net.Http;
using System.Text.Json;
var apiKey = "YOUR_API_KEY";
var videoUrl = Uri.EscapeDataString("https://www.youtube.com/watch?v=dQw4w9WgXcQ");
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", apiKey);
var body = await client.GetStringAsync($"https://api.huntapi.com/v1/video/download?url={videoUrl}&quality=best");
var jobId = JsonDocument.Parse(body).RootElement.GetProperty("job_id").GetString()!;
Console.WriteLine($"Job submitted: {jobId}");
```
</Tab>
<Tab value="Rust">
```rust
use reqwest::Client;
use serde_json::Value;
let client = Client::new();
let api_key = "YOUR_API_KEY";
let video_url = "https://www.youtube.com/watch?v=dQw4w9WgXcQ";
let data = client.get("https://api.huntapi.com/v1/video/download")
.header("x-api-key", api_key)
.query(&[("url", video_url), ("quality", "best")])
.send().await?.json::<Value>().await?;
let job_id = data["job_id"].as_str().unwrap();
println!("Job submitted: {}", job_id);
```
</Tab>
</Tabs>
</Step>
<Step>
### Poll until the video is ready [#poll-until-the-video-is-ready]
Check `GET /v1/job/{job_id}` every few seconds. When `status` becomes `"done"`, the `download_url` field contains the file URL.
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```python
import time
def wait_for_job(job_id: str, poll_interval: int = 5, timeout: int = 300) -> dict:
start = time.time()
while time.time() - start < timeout:
r = requests.get(f"https://api.huntapi.com/v1/job/{job_id}",
headers={"x-api-key": API_KEY})
result = r.json()
status = result.get("status")
print(f" Status: {status}")
if status == "done":
return result
if status == "error":
raise RuntimeError(f"Job failed: {result.get('error')}")
time.sleep(poll_interval)
raise TimeoutError("Job did not complete within the timeout period.")
result = wait_for_job(job_id)
download_url = result["download_url"]
print(f"Ready! Download URL: {download_url}")
```
</Tab>
<Tab value="TypeScript">
```typescript
async function waitForJob(jobId: string, pollMs = 5000, timeoutMs = 300_000) {
const deadline = Date.now() + timeoutMs;
while (Date.now() < deadline) {
const res = await fetch(`https://api.huntapi.com/v1/job/${jobId}`, {
headers: { "x-api-key": API_KEY },
});
const result = await res.json();
console.log(` Status: ${result.status}`);
if (result.status === "done") return result;
if (result.status === "error") throw new Error(`Job failed: ${result.error}`);
await new Promise(r => setTimeout(r, pollMs));
}
throw new Error("Timeout");
}
const result = await waitForJob(jobId);
const downloadUrl = result.download_url;
console.log(`Ready! Download URL: ${downloadUrl}`);
```
</Tab>
<Tab value="PHP">
```php
function waitForJob(string $apiKey, string $jobId, int $pollSec = 5, int $timeoutSec = 300): array {
$start = time();
while (time() - $start < $timeoutSec) {
$ch = curl_init("https://api.huntapi.com/v1/job/{$jobId}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
$status = $result["status"] ?? "";
echo " Status: {$status}\n";
if ($status === "done") return $result;
if ($status === "error") throw new RuntimeException("Job failed: " . ($result["error"] ?? ""));
sleep($pollSec);
}
throw new RuntimeException("Timeout");
}
$result = waitForJob($apiKey, $jobId);
$downloadUrl = $result["download_url"];
echo "Ready! Download URL: {$downloadUrl}\n";
```
</Tab>
<Tab value="Go">
```go
import "time"
func waitForJob(apiKey, jobID string) (map[string]any, error) {
deadline := time.Now().Add(5 * time.Minute)
for time.Now().Before(deadline) {
req, _ := http.NewRequest("GET", "https://api.huntapi.com/v1/job/"+jobID, nil)
req.Header.Set("x-api-key", apiKey)
resp, _ := http.DefaultClient.Do(req)
body, _ := io.ReadAll(resp.Body)
resp.Body.Close()
var result map[string]any
json.Unmarshal(body, &result)
status := result["status"].(string)
fmt.Println(" Status:", status)
if status == "done" { return result, nil }
if status == "error" { return nil, fmt.Errorf("job failed: %v", result["error"]) }
time.Sleep(5 * time.Second)
}
return nil, fmt.Errorf("timeout")
}
result, err := waitForJob(APIKey, jobID)
if err != nil { panic(err) }
downloadURL := result["download_url"].(string)
fmt.Println("Ready! Download URL:", downloadURL)
```
</Tab>
<Tab value="Java">
```java
import java.time.*;
static JSONObject waitForJob(HttpClient client, String apiKey, String jobId) throws Exception {
var deadline = Instant.now().plusSeconds(300);
while (Instant.now().isBefore(deadline)) {
var req = HttpRequest.newBuilder()
.uri(URI.create("https://api.huntapi.com/v1/job/" + jobId))
.header("x-api-key", apiKey).GET().build();
var resp = client.send(req, HttpResponse.BodyHandlers.ofString());
var result = new JSONObject(resp.body());
var status = result.getString("status");
System.out.println(" Status: " + status);
if ("done".equals(status)) return result;
if ("error".equals(status)) throw new RuntimeException("Job failed: " + result.optString("error"));
Thread.sleep(5000);
}
throw new RuntimeException("Timeout");
}
var result = waitForJob(client, apiKey, jobId);
var downloadUrl = result.getString("download_url");
System.out.println("Ready! Download URL: " + downloadUrl);
```
</Tab>
<Tab value="C#">
```csharp
async Task<JsonElement> WaitForJob(HttpClient client, string jobId)
{
var deadline = DateTime.UtcNow.AddMinutes(5);
while (DateTime.UtcNow < deadline)
{
var body = await client.GetStringAsync($"https://api.huntapi.com/v1/job/{jobId}");
var result = JsonDocument.Parse(body).RootElement;
var status = result.GetProperty("status").GetString();
Console.WriteLine($" Status: {status}");
if (status == "done") return result;
if (status == "error") throw new Exception($"Job failed: {result.GetProperty("error")}");
await Task.Delay(5000);
}
throw new TimeoutException("Job did not complete in time.");
}
var result = await WaitForJob(client, jobId);
var downloadUrl = result.GetProperty("download_url").GetString()!;
Console.WriteLine($"Ready! Download URL: {downloadUrl}");
```
</Tab>
<Tab value="Rust">
```rust
use tokio::time::{sleep, Duration};
use std::time::Instant;
async fn wait_for_job(client: &Client, api_key: &str, job_id: &str) -> Value {
let deadline = Instant::now() + Duration::from_secs(300);
loop {
assert!(Instant::now() < deadline, "Timeout");
let result = client.get(format!("https://api.huntapi.com/v1/job/{}", job_id))
.header("x-api-key", api_key)
.send().await.unwrap().json::<Value>().await.unwrap();
let status = result["status"].as_str().unwrap_or("");
println!(" Status: {}", status);
if status == "done" { return result; }
if status == "error" { panic!("Job failed: {}", result["error"]); }
sleep(Duration::from_secs(5)).await;
}
}
let result = wait_for_job(&client, api_key, job_id).await;
let download_url = result["download_url"].as_str().unwrap();
println!("Ready! Download URL: {}", download_url);
```
</Tab>
</Tabs>
</Step>
<Step>
### Download the video file to disk [#download-the-video-file-to-disk]
Stream the file from the `download_url` and save it locally.
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```python
filename = "video.mp4"
with requests.get(download_url, stream=True) as r:
r.raise_for_status()
with open(filename, "wb") as f:
for chunk in r.iter_content(chunk_size=8192):
f.write(chunk)
print(f"Saved to {filename}")
```
</Tab>
<Tab value="TypeScript">
```typescript
import { createWriteStream } from "fs";
import { Readable } from "stream";
const fileResponse = await fetch(downloadUrl);
const writer = createWriteStream("video.mp4");
Readable.fromWeb(fileResponse.body as any).pipe(writer);
await new Promise((resolve, reject) => { writer.on("finish", resolve); writer.on("error", reject); });
console.log("Saved to video.mp4");
```
</Tab>
<Tab value="PHP">
```php
$fp = fopen("video.mp4", "wb");
$ch = curl_init($downloadUrl);
curl_setopt($ch, CURLOPT_FILE, $fp);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
curl_exec($ch);
curl_close($ch);
fclose($fp);
echo "Saved to video.mp4\n";
```
</Tab>
<Tab value="Go">
```go
import "os"
resp, _ := http.Get(downloadURL)
defer resp.Body.Close()
file, _ := os.Create("video.mp4")
defer file.Close()
io.Copy(file, resp.Body)
fmt.Println("Saved to video.mp4")
```
</Tab>
<Tab value="Java">
```java
import java.nio.file.*;
import java.net.URL;
var in = new URL(downloadUrl).openStream();
Files.copy(in, Path.of("video.mp4"), StandardCopyOption.REPLACE_EXISTING);
System.out.println("Saved to video.mp4");
```
</Tab>
<Tab value="C#">
```csharp
using var fileStream = File.Create("video.mp4");
using var download = await new HttpClient().GetStreamAsync(downloadUrl);
await download.CopyToAsync(fileStream);
Console.WriteLine("Saved to video.mp4");
```
</Tab>
<Tab value="Rust">
```rust
use std::io::Write;
use std::fs::File;
let bytes = reqwest::get(download_url).await?.bytes().await?;
let mut file = File::create("video.mp4").unwrap();
file.write_all(&bytes).unwrap();
println!("Saved to video.mp4");
```
</Tab>
</Tabs>
</Step>
</Steps>
<Callout type="info">
You can pass `quality: "best"`, `"1080p"`, `"720p"`, or `"audio"` in the initial request to control the output format before the job is submitted.
</Callout>
# Batch Downloads with Webhooks (/playbooks/huntapi-webhook-batch)
## Overview [#overview]
Instead of polling, you can pass a `webhook_url` when submitting a job. HuntAPI will POST the result to your URL the moment the download is ready. This playbook shows how to:
1. Submit a batch of jobs with a webhook URL
2. Receive and verify the webhook payload
## Prerequisites [#prerequisites]
* A HuntAPI key — get one at [app.huntapi.com](https://app.huntapi.com)
* A publicly reachable HTTP endpoint (use [ngrok](https://ngrok.com) for local testing)
* Install dependencies for your language:
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```bash
pip install requests flask
```
</Tab>
<Tab value="TypeScript">
```bash
npm install express @types/express
```
</Tab>
<Tab value="PHP">
`curl` extension enabled (on by default).
</Tab>
<Tab value="Go">
No extra dependencies — uses `net/http` (Go 1.18+).
</Tab>
<Tab value="Java">
No extra dependencies — uses `com.sun.net.httpserver` (built-in, Java 6+).
</Tab>
<Tab value="C#">
No extra dependencies — uses ASP.NET minimal API (.NET 6+).
</Tab>
<Tab value="Rust">
```toml
# Cargo.toml
[dependencies]
reqwest = { version = "0.12", features = ["json"] }
tokio = { version = "1", features = ["full"] }
serde_json = "1"
axum = "0.7"
```
</Tab>
</Tabs>
## Steps [#steps]
<Steps>
<Step>
### Submit a batch of jobs with a webhook URL [#submit-a-batch-of-jobs-with-a-webhook-url]
Pass your publicly accessible endpoint as `webhook_url`. Each job is independent; HuntAPI will call the webhook when it finishes.
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```python
import requests
API_KEY = "YOUR_API_KEY"
WEBHOOK_URL = "https://yourserver.example.com/webhooks/huntapi"
URLS = [
"https://www.youtube.com/watch?v=VIDEO_ID_1",
"https://www.youtube.com/watch?v=VIDEO_ID_2",
"https://www.youtube.com/watch?v=VIDEO_ID_3",
]
job_ids = []
for video_url in URLS:
r = requests.get(
"https://api.huntapi.com/v1/video/download",
headers={"x-api-key": API_KEY},
params={"url": video_url, "quality": "best", "webhook_url": WEBHOOK_URL},
)
job_id = r.json()["job_id"]
job_ids.append(job_id)
print(f"Submitted: {job_id}")
print(f"\n{len(job_ids)} jobs submitted. Waiting for webhooks...")
```
</Tab>
<Tab value="TypeScript">
```typescript
const API_KEY = "YOUR_API_KEY";
const WEBHOOK_URL = "https://yourserver.example.com/webhooks/huntapi";
const URLS = [
"https://www.youtube.com/watch?v=VIDEO_ID_1",
"https://www.youtube.com/watch?v=VIDEO_ID_2",
"https://www.youtube.com/watch?v=VIDEO_ID_3",
];
const jobIds: string[] = [];
for (const videoUrl of URLS) {
const params = new URLSearchParams({ url: videoUrl, quality: "best", webhook_url: WEBHOOK_URL });
const res = await fetch(`https://api.huntapi.com/v1/video/download?${params}`, {
headers: { "x-api-key": API_KEY },
});
const { job_id } = await res.json();
jobIds.push(job_id);
console.log(`Submitted: ${job_id}`);
}
console.log(`\n${jobIds.length} jobs submitted. Waiting for webhooks...`);
```
</Tab>
<Tab value="PHP">
```php
<?php
$apiKey = "YOUR_API_KEY";
$webhookUrl = "https://yourserver.example.com/webhooks/huntapi";
$urls = [
"https://www.youtube.com/watch?v=VIDEO_ID_1",
"https://www.youtube.com/watch?v=VIDEO_ID_2",
"https://www.youtube.com/watch?v=VIDEO_ID_3",
];
$jobIds = [];
foreach ($urls as $videoUrl) {
$params = http_build_query(["url" => $videoUrl, "quality" => "best", "webhook_url" => $webhookUrl]);
$ch = curl_init("https://api.huntapi.com/v1/video/download?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
$jobIds[] = $data["job_id"];
echo "Submitted: {$data['job_id']}\n";
}
echo count($jobIds) . " jobs submitted. Waiting for webhooks...\n";
```
</Tab>
<Tab value="Go">
```go
package main
import (
"encoding/json"
"fmt"
"io"
"net/http"
"net/url"
)
func submitJob(apiKey, videoURL, webhookURL string) string {
params := url.Values{"url": {videoURL}, "quality": {"best"}, "webhook_url": {webhookURL}}
req, _ := http.NewRequest("GET", "https://api.huntapi.com/v1/video/download?"+params.Encode(), nil)
req.Header.Set("x-api-key", apiKey)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var data map[string]any
json.Unmarshal(body, &data)
return data["job_id"].(string)
}
func main() {
apiKey := "YOUR_API_KEY"
webhookURL := "https://yourserver.example.com/webhooks/huntapi"
urls := []string{
"https://www.youtube.com/watch?v=VIDEO_ID_1",
"https://www.youtube.com/watch?v=VIDEO_ID_2",
"https://www.youtube.com/watch?v=VIDEO_ID_3",
}
for _, u := range urls {
jobID := submitJob(apiKey, u, webhookURL)
fmt.Println("Submitted:", jobID)
}
fmt.Printf("%d jobs submitted. Waiting for webhooks...\n", len(urls))
}
```
</Tab>
<Tab value="Java">
```java
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
import org.json.*;
var client = HttpClient.newHttpClient();
var apiKey = "YOUR_API_KEY";
var webhookUrl = "https://yourserver.example.com/webhooks/huntapi";
var urls = new String[]{
"https://www.youtube.com/watch?v=VIDEO_ID_1",
"https://www.youtube.com/watch?v=VIDEO_ID_2",
"https://www.youtube.com/watch?v=VIDEO_ID_3",
};
for (var videoUrl : urls) {
var encoded = URLEncoder.encode(videoUrl, StandardCharsets.UTF_8);
var wh = URLEncoder.encode(webhookUrl, StandardCharsets.UTF_8);
var url = "https://api.huntapi.com/v1/video/download?url=" + encoded + "&quality=best&webhook_url=" + wh;
var req = HttpRequest.newBuilder().uri(URI.create(url))
.header("x-api-key", apiKey).GET().build();
var resp = client.send(req, HttpResponse.BodyHandlers.ofString());
var jobId = new JSONObject(resp.body()).getString("job_id");
System.out.println("Submitted: " + jobId);
}
```
</Tab>
<Tab value="C#">
```csharp
using System.Net.Http;
using System.Text.Json;
var apiKey = "YOUR_API_KEY";
var webhookUrl = Uri.EscapeDataString("https://yourserver.example.com/webhooks/huntapi");
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", apiKey);
var urls = new[]
{
"https://www.youtube.com/watch?v=VIDEO_ID_1",
"https://www.youtube.com/watch?v=VIDEO_ID_2",
"https://www.youtube.com/watch?v=VIDEO_ID_3",
};
foreach (var videoUrl in urls)
{
var encoded = Uri.EscapeDataString(videoUrl);
var body = await client.GetStringAsync(
$"https://api.huntapi.com/v1/video/download?url={encoded}&quality=best&webhook_url={webhookUrl}");
var jobId = JsonDocument.Parse(body).RootElement.GetProperty("job_id").GetString();
Console.WriteLine($"Submitted: {jobId}");
}
```
</Tab>
<Tab value="Rust">
```rust
use reqwest::Client;
use serde_json::Value;
#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
let client = Client::new();
let api_key = "YOUR_API_KEY";
let webhook_url = "https://yourserver.example.com/webhooks/huntapi";
let urls = [
"https://www.youtube.com/watch?v=VIDEO_ID_1",
"https://www.youtube.com/watch?v=VIDEO_ID_2",
"https://www.youtube.com/watch?v=VIDEO_ID_3",
];
for video_url in &urls {
let data = client.get("https://api.huntapi.com/v1/video/download")
.header("x-api-key", api_key)
.query(&[("url", video_url), ("quality", &"best"), ("webhook_url", &webhook_url)])
.send().await?.json::<Value>().await?;
println!("Submitted: {}", data["job_id"].as_str().unwrap_or(""));
}
Ok(())
}
```
</Tab>
</Tabs>
</Step>
<Step>
### Build a webhook receiver [#build-a-webhook-receiver]
HuntAPI will POST a JSON body to your endpoint with `job_id`, `status`, and `download_url` when the job completes.
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```python
from flask import Flask, request, jsonify
app = Flask(__name__)
@app.route("/webhooks/huntapi", methods=["POST"])
def huntapi_webhook():
payload = request.get_json()
job_id = payload.get("job_id")
status = payload.get("status")
download_url = payload.get("download_url")
print(f"Webhook received — Job: {job_id}, Status: {status}")
if status == "done" and download_url:
# Trigger your download or further processing here
print(f" Download URL: {download_url}")
return jsonify({"received": True}), 200
if __name__ == "__main__":
app.run(port=3000)
```
</Tab>
<Tab value="TypeScript">
```typescript
import express from "express";
const app = express();
app.use(express.json());
app.post("/webhooks/huntapi", (req, res) => {
const { job_id, status, download_url } = req.body;
console.log(`Webhook received — Job: ${job_id}, Status: ${status}`);
if (status === "done" && download_url) {
// Trigger your download or further processing here
console.log(` Download URL: ${download_url}`);
}
res.json({ received: true });
});
app.listen(3000, () => console.log("Webhook listener on :3000"));
```
</Tab>
<Tab value="PHP">
```php
<?php
// webhook.php — place this file on a public server
$payload = json_decode(file_get_contents("php://input"), true);
$jobId = $payload["job_id"] ?? "";
$status = $payload["status"] ?? "";
$downloadUrl = $payload["download_url"] ?? "";
error_log("Webhook received — Job: {$jobId}, Status: {$status}");
if ($status === "done" && $downloadUrl) {
// Trigger your download or further processing here
error_log(" Download URL: {$downloadUrl}");
}
http_response_code(200);
echo json_encode(["received" => true]);
```
</Tab>
<Tab value="Go">
```go
package main
import (
"encoding/json"
"fmt"
"net/http"
)
func main() {
http.HandleFunc("/webhooks/huntapi", func(w http.ResponseWriter, r *http.Request) {
var payload map[string]any
json.NewDecoder(r.Body).Decode(&payload)
jobID := payload["job_id"]
status := payload["status"]
downloadURL := payload["download_url"]
fmt.Printf("Webhook received — Job: %v, Status: %v\n", jobID, status)
if status == "done" && downloadURL != nil {
fmt.Println(" Download URL:", downloadURL)
// Trigger download or further processing here
}
w.Header().Set("Content-Type", "application/json")
w.Write([]byte(`{"received":true}`))
})
fmt.Println("Webhook listener on :3000")
http.ListenAndServe(":3000", nil)
}
```
</Tab>
<Tab value="Java">
```java
import com.sun.net.httpserver.*;
import java.net.InetSocketAddress;
import org.json.*;
public class WebhookServer {
public static void main(String[] args) throws Exception {
var server = HttpServer.create(new InetSocketAddress(3000), 0);
server.createContext("/webhooks/huntapi", exchange -> {
var body = exchange.getRequestBody().readAllBytes();
var payload = new JSONObject(new String(body));
var jobId = payload.optString("job_id");
var status = payload.optString("status");
var downloadUrl = payload.optString("download_url");
System.out.printf("Webhook received — Job: %s, Status: %s%n", jobId, status);
if ("done".equals(status) && !downloadUrl.isEmpty()) {
System.out.println(" Download URL: " + downloadUrl);
}
var resp = "{\"received\":true}".getBytes();
exchange.sendResponseHeaders(200, resp.length);
exchange.getResponseBody().write(resp);
exchange.close();
});
server.start();
System.out.println("Webhook listener on :3000");
}
}
```
</Tab>
<Tab value="C#">
```csharp
using System.Text.Json;
var app = WebApplication.Create();
app.MapPost("/webhooks/huntapi", async (HttpContext ctx) =>
{
using var reader = new StreamReader(ctx.Request.Body);
var body = await reader.ReadToEndAsync();
var payload = JsonDocument.Parse(body).RootElement;
var jobId = payload.GetProperty("job_id").GetString();
var status = payload.GetProperty("status").GetString();
var downloadUrl = payload.TryGetProperty("download_url", out var d) ? d.GetString() : null;
Console.WriteLine($"Webhook received — Job: {jobId}, Status: {status}");
if (status == "done" && downloadUrl != null)
Console.WriteLine($" Download URL: {downloadUrl}");
return Results.Json(new { received = true });
});
Console.WriteLine("Webhook listener on :3000");
app.Run("http://0.0.0.0:3000");
```
</Tab>
<Tab value="Rust">
```rust
use axum::{extract::Json as AxumJson, routing::post, Router};
use serde_json::{json, Value};
async fn huntapi_webhook(AxumJson(payload): AxumJson<Value>) -> AxumJson<Value> {
let job_id = payload["job_id"].as_str().unwrap_or("");
let status = payload["status"].as_str().unwrap_or("");
let download_url = payload["download_url"].as_str().unwrap_or("");
println!("Webhook received — Job: {}, Status: {}", job_id, status);
if status == "done" && !download_url.is_empty() {
println!(" Download URL: {}", download_url);
}
AxumJson(json!({ "received": true }))
}
#[tokio::main]
async fn main() {
let app = Router::new().route("/webhooks/huntapi", post(huntapi_webhook));
let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
println!("Webhook listener on :3000");
axum::serve(listener, app).await.unwrap();
}
```
</Tab>
</Tabs>
</Step>
<Step>
### Test locally with ngrok [#test-locally-with-ngrok]
During development, use ngrok to expose your local server to the internet so HuntAPI can reach your webhook.
```bash
# Start your local server first, then:
ngrok http 3000
```
Copy the generated `https://xxxx.ngrok.io` URL and use it as your `webhook_url` parameter.
</Step>
</Steps>
<Callout type="info">
Your webhook endpoint must return a `2xx` status code within 10 seconds, otherwise HuntAPI will retry the delivery. Make heavy processing asynchronous and acknowledge the webhook immediately.
</Callout>
# Find a Professional Email (/playbooks/piloterr-email-finder)
## Overview [#overview]
This playbook shows how to find and verify a professional email address for a prospect. Use it in outbound sales pipelines to auto-enrich contact records before sending a sequence.
## Prerequisites [#prerequisites]
* A Piloterr API key — get one at [app.piloterr.com](https://app.piloterr.com)
* Install dependencies for your language:
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```bash
pip install requests
```
</Tab>
<Tab value="TypeScript">
No extra dependencies — uses the native `fetch` API (Node 18+).
</Tab>
<Tab value="PHP">
`curl` extension enabled (on by default).
</Tab>
<Tab value="Go">
No extra dependencies — uses `net/http` (Go 1.18+).
</Tab>
<Tab value="Java">
No extra dependencies — uses `java.net.http` (Java 11+).
</Tab>
<Tab value="C#">
No extra dependencies — uses `System.Net.Http` (.NET 6+).
</Tab>
<Tab value="Rust">
```toml
# Cargo.toml
[dependencies]
reqwest = { version = "0.12", features = ["json"] }
tokio = { version = "1", features = ["full"] }
serde_json = "1"
```
</Tab>
</Tabs>
## Steps [#steps]
<Steps>
<Step>
### Find an email address [#find-an-email-address]
Call `GET /v2/email/finder` with `first_name`, `last_name`, and `domain`.
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```python
import requests
API_KEY = "YOUR_API_KEY"
response = requests.get(
"https://api.piloterr.com/v2/email/finder",
headers={"x-api-key": API_KEY},
params={"first_name": "Patrick", "last_name": "Collison", "domain": "stripe.com"},
)
result = response.json()
print(result)
```
</Tab>
<Tab value="TypeScript">
```typescript
const API_KEY = "YOUR_API_KEY";
const params = new URLSearchParams({ first_name: "Patrick", last_name: "Collison", domain: "stripe.com" });
const response = await fetch(`https://api.piloterr.com/v2/email/finder?${params}`, {
headers: { "x-api-key": API_KEY },
});
const result = await response.json();
console.log(result);
```
</Tab>
<Tab value="PHP">
```php
<?php
$apiKey = "YOUR_API_KEY";
$params = http_build_query(["first_name" => "Patrick", "last_name" => "Collison", "domain" => "stripe.com"]);
$ch = curl_init("https://api.piloterr.com/v2/email/finder?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($result);
```
</Tab>
<Tab value="Go">
```go
package main
import (
"encoding/json"
"fmt"
"io"
"net/http"
"net/url"
)
func main() {
params := url.Values{
"first_name": {"Patrick"}, "last_name": {"Collison"}, "domain": {"stripe.com"},
}
req, _ := http.NewRequest("GET", "https://api.piloterr.com/v2/email/finder?"+params.Encode(), nil)
req.Header.Set("x-api-key", "YOUR_API_KEY")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var result map[string]any
json.Unmarshal(body, &result)
fmt.Println(result)
}
```
</Tab>
<Tab value="Java">
```java
import java.net.URI;
import java.net.http.*;
var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://api.piloterr.com/v2/email/finder?first_name=Patrick&last_name=Collison&domain=stripe.com"))
.header("x-api-key", "YOUR_API_KEY")
.GET().build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```
</Tab>
<Tab value="C#">
```csharp
using System.Net.Http;
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");
var body = await client.GetStringAsync(
"https://api.piloterr.com/v2/email/finder?first_name=Patrick&last_name=Collison&domain=stripe.com");
Console.WriteLine(body);
```
</Tab>
<Tab value="Rust">
```rust
#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
let result = reqwest::Client::new()
.get("https://api.piloterr.com/v2/email/finder")
.header("x-api-key", "YOUR_API_KEY")
.query(&[("first_name", "Patrick"), ("last_name", "Collison"), ("domain", "stripe.com")])
.send().await?.json::<serde_json::Value>().await?;
println!("{:#?}", result);
Ok(())
}
```
</Tab>
</Tabs>
</Step>
<Step>
### Inspect the result [#inspect-the-result]
The response includes `email`, `confidence` (0–100), `status` (`valid`, `risky`, `invalid`), and the detected email pattern.
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```python
email = result.get("email")
confidence = result.get("confidence")
status = result.get("status")
if email and confidence >= 70:
print(f"✓ Found: {email} (confidence: {confidence}%, status: {status})")
else:
print(f"✗ Email not found or low confidence (status: {status})")
```
</Tab>
<Tab value="TypeScript">
```typescript
const { email, confidence, status } = result;
if (email && confidence >= 70) {
console.log(`✓ Found: ${email} (confidence: ${confidence}%, status: ${status})`);
} else {
console.log(`✗ Email not found or low confidence (status: ${status})`);
}
```
</Tab>
<Tab value="PHP">
```php
$email = $result["email"] ?? null;
$confidence = $result["confidence"] ?? 0;
$status = $result["status"] ?? "unknown";
if ($email && $confidence >= 70) {
echo "✓ Found: {$email} (confidence: {$confidence}%, status: {$status})\n";
} else {
echo "✗ Email not found or low confidence (status: {$status})\n";
}
```
</Tab>
<Tab value="Go">
```go
email := result["email"]
confidence := result["confidence"]
status := result["status"]
if email != nil && confidence.(float64) >= 70 {
fmt.Printf("✓ Found: %v (confidence: %.0f%%, status: %v)\n", email, confidence, status)
} else {
fmt.Printf("✗ Email not found or low confidence (status: %v)\n", status)
}
```
</Tab>
<Tab value="Java">
```java
import org.json.*;
var r = new JSONObject(response.body());
var email = r.optString("email", null);
var confidence = r.optInt("confidence", 0);
var status = r.optString("status", "unknown");
if (email != null && confidence >= 70) {
System.out.printf("✓ Found: %s (confidence: %d%%, status: %s)%n", email, confidence, status);
} else {
System.out.printf("✗ Email not found or low confidence (status: %s)%n", status);
}
```
</Tab>
<Tab value="C#">
```csharp
using System.Text.Json;
var r = JsonDocument.Parse(body).RootElement;
var email = r.TryGetProperty("email", out var e) ? e.GetString() : null;
var confidence = r.TryGetProperty("confidence", out var c) ? c.GetInt32() : 0;
var status = r.TryGetProperty("status", out var s) ? s.GetString() : "unknown";
if (email != null && confidence >= 70)
Console.WriteLine($"✓ Found: {email} (confidence: {confidence}%, status: {status})");
else
Console.WriteLine($"✗ Email not found or low confidence (status: {status})");
```
</Tab>
<Tab value="Rust">
```rust
let email = result["email"].as_str().unwrap_or("");
let confidence = result["confidence"].as_i64().unwrap_or(0);
let status = result["status"].as_str().unwrap_or("unknown");
if !email.is_empty() && confidence >= 70 {
println!("✓ Found: {} (confidence: {}%, status: {})", email, confidence, status);
} else {
println!("✗ Email not found or low confidence (status: {})", status);
}
```
</Tab>
</Tabs>
</Step>
<Step>
### Enrich a list of prospects from a CSV [#enrich-a-list-of-prospects-from-a-csv]
Load a CSV of prospects, find their emails, and write results back out.
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```python
import csv, time, requests
API_KEY = "YOUR_API_KEY"
def find_email(first: str, last: str, domain: str) -> dict:
r = requests.get("https://api.piloterr.com/v2/email/finder",
headers={"x-api-key": API_KEY},
params={"first_name": first, "last_name": last, "domain": domain})
return r.json()
prospects = [
{"first_name": "Patrick", "last_name": "Collison", "domain": "stripe.com"},
{"first_name": "Sam", "last_name": "Altman", "domain": "openai.com"},
{"first_name": "Tobi", "last_name": "Lutke", "domain": "shopify.com"},
]
with open("prospects_enriched.csv", "w", newline="") as f:
fieldnames = ["first_name", "last_name", "domain", "email", "confidence", "status"]
writer = csv.DictWriter(f, fieldnames=fieldnames)
writer.writeheader()
for p in prospects:
result = find_email(p["first_name"], p["last_name"], p["domain"])
writer.writerow({**p, "email": result.get("email", ""), "confidence": result.get("confidence", 0), "status": result.get("status", "")})
time.sleep(0.5)
print("Done! Results saved to prospects_enriched.csv")
```
</Tab>
<Tab value="TypeScript">
```typescript
import { createWriteStream } from "fs";
const API_KEY = "YOUR_API_KEY";
const prospects = [
{ first_name: "Patrick", last_name: "Collison", domain: "stripe.com" },
{ first_name: "Sam", last_name: "Altman", domain: "openai.com" },
{ first_name: "Tobi", last_name: "Lutke", domain: "shopify.com" },
];
const rows: string[] = ["first_name,last_name,domain,email,confidence,status"];
for (const p of prospects) {
const params = new URLSearchParams({ first_name: p.first_name, last_name: p.last_name, domain: p.domain });
const res = await fetch(`https://api.piloterr.com/v2/email/finder?${params}`, {
headers: { "x-api-key": API_KEY },
});
const r = await res.json();
rows.push(`${p.first_name},${p.last_name},${p.domain},${r.email ?? ""},${r.confidence ?? 0},${r.status ?? ""}`);
await new Promise(resolve => setTimeout(resolve, 500));
}
import { writeFileSync } from "fs";
writeFileSync("prospects_enriched.csv", rows.join("\n"));
console.log("Done! Results saved to prospects_enriched.csv");
```
</Tab>
<Tab value="PHP">
```php
<?php
$apiKey = "YOUR_API_KEY";
$prospects = [
["first_name" => "Patrick", "last_name" => "Collison", "domain" => "stripe.com"],
["first_name" => "Sam", "last_name" => "Altman", "domain" => "openai.com"],
["first_name" => "Tobi", "last_name" => "Lutke", "domain" => "shopify.com"],
];
$fp = fopen("prospects_enriched.csv", "w");
fputcsv($fp, ["first_name", "last_name", "domain", "email", "confidence", "status"]);
foreach ($prospects as $p) {
$params = http_build_query(array_merge($p, ["query" => ""]));
$ch = curl_init("https://api.piloterr.com/v2/email/finder?" . http_build_query($p));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]);
$r = json_decode(curl_exec($ch), true);
curl_close($ch);
fputcsv($fp, [$p["first_name"], $p["last_name"], $p["domain"],
$r["email"] ?? "", $r["confidence"] ?? 0, $r["status"] ?? ""]);
usleep(500000);
}
fclose($fp);
echo "Done! Results saved to prospects_enriched.csv\n";
```
</Tab>
<Tab value="Go">
```go
package main
import (
"encoding/csv"
"encoding/json"
"io"
"net/http"
"net/url"
"os"
"strconv"
"time"
)
type Prospect struct{ FirstName, LastName, Domain string }
func findEmail(apiKey string, p Prospect) map[string]any {
params := url.Values{"first_name": {p.FirstName}, "last_name": {p.LastName}, "domain": {p.Domain}}
req, _ := http.NewRequest("GET", "https://api.piloterr.com/v2/email/finder?"+params.Encode(), nil)
req.Header.Set("x-api-key", apiKey)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var r map[string]any
json.Unmarshal(body, &r)
return r
}
func main() {
apiKey := "YOUR_API_KEY"
prospects := []Prospect{
{"Patrick", "Collison", "stripe.com"},
{"Sam", "Altman", "openai.com"},
{"Tobi", "Lutke", "shopify.com"},
}
f, _ := os.Create("prospects_enriched.csv")
w := csv.NewWriter(f)
w.Write([]string{"first_name", "last_name", "domain", "email", "confidence", "status"})
for _, p := range prospects {
r := findEmail(apiKey, p)
confidence := strconv.FormatFloat(r["confidence"].(float64), 'f', 0, 64)
w.Write([]string{p.FirstName, p.LastName, p.Domain,
r["email"].(string), confidence, r["status"].(string)})
time.Sleep(500 * time.Millisecond)
}
w.Flush()
f.Close()
}
```
</Tab>
<Tab value="Java">
```java
import java.net.URI;
import java.net.http.*;
import java.nio.file.*;
import java.util.*;
import org.json.*;
public class Main {
public static void main(String[] args) throws Exception {
var client = HttpClient.newHttpClient();
var apiKey = "YOUR_API_KEY";
var prospects = List.of(
Map.of("first_name","Patrick","last_name","Collison","domain","stripe.com"),
Map.of("first_name","Sam", "last_name","Altman", "domain","openai.com"),
Map.of("first_name","Tobi", "last_name","Lutke", "domain","shopify.com"));
var lines = new ArrayList<String>();
lines.add("first_name,last_name,domain,email,confidence,status");
for (var p : prospects) {
var url = "https://api.piloterr.com/v2/email/finder?first_name=" + p.get("first_name")
+ "&last_name=" + p.get("last_name") + "&domain=" + p.get("domain");
var req = HttpRequest.newBuilder().uri(URI.create(url))
.header("x-api-key", apiKey).GET().build();
var resp = client.send(req, HttpResponse.BodyHandlers.ofString());
var r = new JSONObject(resp.body());
lines.add(String.join(",", p.get("first_name"), p.get("last_name"), p.get("domain"),
r.optString("email",""), String.valueOf(r.optInt("confidence")), r.optString("status","")));
Thread.sleep(500);
}
Files.write(Path.of("prospects_enriched.csv"), lines);
System.out.println("Done! Results saved to prospects_enriched.csv");
}
}
```
</Tab>
<Tab value="C#">
```csharp
using System.Net.Http;
using System.Text.Json;
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");
var prospects = new[] {
(first: "Patrick", last: "Collison", domain: "stripe.com"),
(first: "Sam", last: "Altman", domain: "openai.com"),
(first: "Tobi", last: "Lutke", domain: "shopify.com"),
};
var lines = new List<string> { "first_name,last_name,domain,email,confidence,status" };
foreach (var p in prospects)
{
var body = await client.GetStringAsync(
$"https://api.piloterr.com/v2/email/finder?first_name={p.first}&last_name={p.last}&domain={p.domain}");
var r = JsonDocument.Parse(body).RootElement;
var email = r.TryGetProperty("email", out var e) ? e.GetString() : "";
var confidence = r.TryGetProperty("confidence", out var c) ? c.GetInt32().ToString() : "0";
var status = r.TryGetProperty("status", out var s) ? s.GetString() : "";
lines.Add($"{p.first},{p.last},{p.domain},{email},{confidence},{status}");
await Task.Delay(500);
}
File.WriteAllLines("prospects_enriched.csv", lines);
Console.WriteLine("Done! Results saved to prospects_enriched.csv");
```
</Tab>
<Tab value="Rust">
```rust
use reqwest::Client;
use serde_json::Value;
use std::{fs::File, io::Write, time::Duration};
use tokio::time::sleep;
#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
let client = Client::new();
let api_key = "YOUR_API_KEY";
let prospects = vec![
("Patrick", "Collison", "stripe.com"),
("Sam", "Altman", "openai.com"),
("Tobi", "Lutke", "shopify.com"),
];
let mut file = File::create("prospects_enriched.csv").unwrap();
writeln!(file, "first_name,last_name,domain,email,confidence,status").unwrap();
for (first, last, domain) in &prospects {
let r = client.get("https://api.piloterr.com/v2/email/finder")
.header("x-api-key", api_key)
.query(&[("first_name", first), ("last_name", last), ("domain", domain)])
.send().await?.json::<Value>().await?;
writeln!(file, "{},{},{},{},{},{}",
first, last, domain,
r["email"].as_str().unwrap_or(""),
r["confidence"].as_i64().unwrap_or(0),
r["status"].as_str().unwrap_or("")).unwrap();
sleep(Duration::from_millis(500)).await;
}
println!("Done! Results saved to prospects_enriched.csv");
Ok(())
}
```
</Tab>
</Tabs>
</Step>
</Steps>
<Callout type="info">
Only use emails with `confidence >= 70` and `status == "valid"` in cold outreach. Lower-confidence addresses risk bounces that harm your domain reputation.
</Callout>
# Enrich a Lead with LinkedIn (/playbooks/piloterr-linkedin-enrichment)
## Overview [#overview]
This playbook builds a **CRM enrichment pipeline**: given a company's website domain, fetch its LinkedIn profile and extract structured data like industry, employee count, headquarters, and specialities.
## Prerequisites [#prerequisites]
* A Piloterr API key — get one at [app.piloterr.com](https://app.piloterr.com)
* Install dependencies for your language:
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```bash
pip install requests
```
</Tab>
<Tab value="TypeScript">
No extra dependencies — uses the native `fetch` API (Node 18+).
</Tab>
<Tab value="PHP">
`curl` extension enabled (on by default in most PHP installs).
</Tab>
<Tab value="Go">
No extra dependencies — uses `net/http` (Go 1.18+).
</Tab>
<Tab value="Java">
No extra dependencies — uses `java.net.http` (Java 11+).
</Tab>
<Tab value="C#">
No extra dependencies — uses `System.Net.Http` (.NET 6+).
</Tab>
<Tab value="Rust">
```toml
# Cargo.toml
[dependencies]
reqwest = { version = "0.12", features = ["json"] }
tokio = { version = "1", features = ["full"] }
serde_json = "1"
```
</Tab>
</Tabs>
## Steps [#steps]
<Steps>
<Step>
### Look up a company by domain [#look-up-a-company-by-domain]
Pass the company's website domain to the `domain` parameter. You can also use a LinkedIn URL via `query`.
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```python
import requests
API_KEY = "YOUR_API_KEY"
response = requests.get(
"https://api.piloterr.com/v2/linkedin/company/info",
headers={"x-api-key": API_KEY},
params={"domain": "stripe.com"},
)
company = response.json()
print(company)
```
</Tab>
<Tab value="TypeScript">
```typescript
const API_KEY = "YOUR_API_KEY";
const params = new URLSearchParams({ domain: "stripe.com" });
const response = await fetch(`https://api.piloterr.com/v2/linkedin/company/info?${params}`, {
headers: { "x-api-key": API_KEY },
});
const company = await response.json();
console.log(company);
```
</Tab>
<Tab value="PHP">
```php
<?php
$apiKey = "YOUR_API_KEY";
$params = http_build_query(["domain" => "stripe.com"]);
$ch = curl_init("https://api.piloterr.com/v2/linkedin/company/info?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]);
$company = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($company);
```
</Tab>
<Tab value="Go">
```go
package main
import (
"encoding/json"
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET",
"https://api.piloterr.com/v2/linkedin/company/info?domain=stripe.com", nil)
req.Header.Set("x-api-key", "YOUR_API_KEY")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var company map[string]any
json.Unmarshal(body, &company)
fmt.Println(company)
}
```
</Tab>
<Tab value="Java">
```java
import java.net.URI;
import java.net.http.*;
var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://api.piloterr.com/v2/linkedin/company/info?domain=stripe.com"))
.header("x-api-key", "YOUR_API_KEY")
.GET().build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```
</Tab>
<Tab value="C#">
```csharp
using System.Net.Http;
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");
var body = await client.GetStringAsync(
"https://api.piloterr.com/v2/linkedin/company/info?domain=stripe.com");
Console.WriteLine(body);
```
</Tab>
<Tab value="Rust">
```rust
#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
let company = reqwest::Client::new()
.get("https://api.piloterr.com/v2/linkedin/company/info")
.header("x-api-key", "YOUR_API_KEY")
.query(&[("domain", "stripe.com")])
.send().await?.json::<serde_json::Value>().await?;
println!("{:#?}", company);
Ok(())
}
```
</Tab>
</Tabs>
</Step>
<Step>
### Extract key company fields [#extract-key-company-fields]
The response contains `company_name`, `industry`, `staff_count`, `staff_range`, `tagline`, `description`, `headquarter`, and `specialities`.
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```python
print(f"Company : {company.get('company_name')}")
print(f"Industry : {company.get('industry')}")
print(f"Employees : {company.get('staff_count')} ({company.get('staff_range')})")
print(f"Website : {company.get('website')}")
hq = company.get("headquarter", {})
print(f"HQ : {hq.get('city')}, {hq.get('country')}")
print(f"Topics : {', '.join(company.get('specialities', [])[:5])}")
```
</Tab>
<Tab value="TypeScript">
```typescript
console.log(`Company : ${company.company_name}`);
console.log(`Industry : ${company.industry}`);
console.log(`Employees : ${company.staff_count} (${company.staff_range})`);
console.log(`Website : ${company.website}`);
console.log(`HQ : ${company.headquarter?.city}, ${company.headquarter?.country}`);
console.log(`Topics : ${(company.specialities ?? []).slice(0, 5).join(", ")}`);
```
</Tab>
<Tab value="PHP">
```php
echo "Company : {$company['company_name']}\n";
echo "Industry : {$company['industry']}\n";
echo "Employees : {$company['staff_count']} ({$company['staff_range']})\n";
echo "HQ : {$company['headquarter']['city']}, {$company['headquarter']['country']}\n";
echo "Topics : " . implode(", ", array_slice($company["specialities"] ?? [], 0, 5)) . "\n";
```
</Tab>
<Tab value="Go">
```go
c := company
fmt.Printf("Company : %v\nIndustry : %v\nEmployees : %v (%v)\nWebsite : %v\n",
c["company_name"], c["industry"], c["staff_count"], c["staff_range"], c["website"])
if hq, ok := c["headquarter"].(map[string]any); ok {
fmt.Printf("HQ : %v, %v\n", hq["city"], hq["country"])
}
```
</Tab>
<Tab value="Java">
```java
import org.json.*;
var c = new JSONObject(response.body());
System.out.printf("Company : %s%nIndustry : %s%nEmployees : %d (%s)%nWebsite : %s%n",
c.getString("company_name"), c.getString("industry"),
c.getInt("staff_count"), c.getString("staff_range"), c.getString("website"));
var hq = c.optJSONObject("headquarter");
if (hq != null) System.out.printf("HQ : %s, %s%n", hq.getString("city"), hq.getString("country"));
```
</Tab>
<Tab value="C#">
```csharp
using System.Text.Json;
var c = JsonDocument.Parse(body).RootElement;
Console.WriteLine($"Company : {c.GetProperty("company_name")}");
Console.WriteLine($"Industry : {c.GetProperty("industry")}");
Console.WriteLine($"Employees : {c.GetProperty("staff_count")} ({c.GetProperty("staff_range")})");
Console.WriteLine($"Website : {c.GetProperty("website")}");
var hq = c.GetProperty("headquarter");
Console.WriteLine($"HQ : {hq.GetProperty("city")}, {hq.GetProperty("country")}");
```
</Tab>
<Tab value="Rust">
```rust
let c = &company;
println!("Company : {}", c["company_name"].as_str().unwrap_or(""));
println!("Industry : {}", c["industry"].as_str().unwrap_or(""));
println!("Employees : {} ({})", c["staff_count"], c["staff_range"].as_str().unwrap_or(""));
println!("HQ : {}, {}", c["headquarter"]["city"].as_str().unwrap_or(""), c["headquarter"]["country"].as_str().unwrap_or(""));
```
</Tab>
</Tabs>
</Step>
<Step>
### Enrich a batch of leads [#enrich-a-batch-of-leads]
Loop over a list of email domains and build enriched company records ready to push to your CRM.
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```python
import json, time, requests
API_KEY = "YOUR_API_KEY"
leads = [
{"email": "alice@stripe.com", "domain": "stripe.com"},
{"email": "bob@notion.so", "domain": "notion.so"},
{"email": "carol@figma.com", "domain": "figma.com"},
]
enriched = []
for lead in leads:
r = requests.get("https://api.piloterr.com/v2/linkedin/company/info",
headers={"x-api-key": API_KEY}, params={"domain": lead["domain"]})
if r.status_code == 200:
c = r.json()
enriched.append({"email": lead["email"], "domain": lead["domain"],
"company": c.get("company_name"), "industry": c.get("industry"),
"employees": c.get("staff_count"), "hq_country": c.get("headquarter", {}).get("country"),
"linkedin_url": c.get("company_url")})
time.sleep(0.5)
with open("enriched_leads.json", "w") as f:
json.dump(enriched, f, indent=2)
print(f"Enriched {len(enriched)} leads → enriched_leads.json")
```
</Tab>
<Tab value="TypeScript">
```typescript
import { writeFileSync } from "fs";
const API_KEY = "YOUR_API_KEY";
const leads = [
{ email: "alice@stripe.com", domain: "stripe.com" },
{ email: "bob@notion.so", domain: "notion.so" },
{ email: "carol@figma.com", domain: "figma.com" },
];
const enriched: any[] = [];
for (const lead of leads) {
const params = new URLSearchParams({ domain: lead.domain });
const res = await fetch(`https://api.piloterr.com/v2/linkedin/company/info?${params}`, {
headers: { "x-api-key": API_KEY },
});
if (res.ok) {
const c = await res.json();
enriched.push({ email: lead.email, domain: lead.domain, company: c.company_name,
industry: c.industry, employees: c.staff_count, hq_country: c.headquarter?.country,
linkedin_url: c.company_url });
}
await new Promise(r => setTimeout(r, 500));
}
writeFileSync("enriched_leads.json", JSON.stringify(enriched, null, 2));
console.log(`Enriched ${enriched.length} leads → enriched_leads.json`);
```
</Tab>
<Tab value="PHP">
```php
<?php
$apiKey = "YOUR_API_KEY";
$leads = [
["email" => "alice@stripe.com", "domain" => "stripe.com"],
["email" => "bob@notion.so", "domain" => "notion.so"],
["email" => "carol@figma.com", "domain" => "figma.com"],
];
$enriched = [];
foreach ($leads as $lead) {
$params = http_build_query(["domain" => $lead["domain"]]);
$ch = curl_init("https://api.piloterr.com/v2/linkedin/company/info?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]);
$c = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) === 200) {
$enriched[] = ["email" => $lead["email"], "domain" => $lead["domain"],
"company" => $c["company_name"] ?? null, "industry" => $c["industry"] ?? null,
"employees" => $c["staff_count"] ?? null, "hq_country" => $c["headquarter"]["country"] ?? null];
}
curl_close($ch);
usleep(500000);
}
file_put_contents("enriched_leads.json", json_encode($enriched, JSON_PRETTY_PRINT));
echo "Enriched " . count($enriched) . " leads → enriched_leads.json\n";
```
</Tab>
<Tab value="Go">
```go
package main
import (
"encoding/json"
"fmt"
"io"
"net/http"
"os"
"time"
)
func enrichDomain(apiKey, domain string) map[string]any {
req, _ := http.NewRequest("GET",
"https://api.piloterr.com/v2/linkedin/company/info?domain="+domain, nil)
req.Header.Set("x-api-key", apiKey)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var c map[string]any
json.Unmarshal(body, &c)
return c
}
func main() {
apiKey := "YOUR_API_KEY"
leads := []struct{ Email, Domain string }{
{"alice@stripe.com", "stripe.com"},
{"bob@notion.so", "notion.so"},
{"carol@figma.com", "figma.com"},
}
var enriched []map[string]any
for _, lead := range leads {
c := enrichDomain(apiKey, lead.Domain)
hq, _ := c["headquarter"].(map[string]any)
enriched = append(enriched, map[string]any{
"email": lead.Email, "domain": lead.Domain,
"company": c["company_name"], "industry": c["industry"],
"employees": c["staff_count"], "hq_country": hq["country"],
})
time.Sleep(500 * time.Millisecond)
}
b, _ := json.MarshalIndent(enriched, "", " ")
os.WriteFile("enriched_leads.json", b, 0644)
fmt.Printf("Enriched %d leads → enriched_leads.json\n", len(enriched))
}
```
</Tab>
<Tab value="Java">
```java
import java.net.URI;
import java.net.http.*;
import java.nio.file.*;
import java.util.*;
import org.json.*;
public class Main {
public static void main(String[] args) throws Exception {
var client = HttpClient.newHttpClient();
var apiKey = "YOUR_API_KEY";
var leads = List.of(
Map.of("email", "alice@stripe.com", "domain", "stripe.com"),
Map.of("email", "bob@notion.so", "domain", "notion.so"),
Map.of("email", "carol@figma.com", "domain", "figma.com"));
var enriched = new JSONArray();
for (var lead : leads) {
var url = "https://api.piloterr.com/v2/linkedin/company/info?domain=" + lead.get("domain");
var req = HttpRequest.newBuilder().uri(URI.create(url))
.header("x-api-key", apiKey).GET().build();
var resp = client.send(req, HttpResponse.BodyHandlers.ofString());
if (resp.statusCode() == 200) {
var c = new JSONObject(resp.body());
var hq = c.optJSONObject("headquarter");
enriched.put(new JSONObject()
.put("email", lead.get("email"))
.put("domain", lead.get("domain"))
.put("company", c.optString("company_name"))
.put("industry", c.optString("industry"))
.put("employees", c.optInt("staff_count"))
.put("hq_country", hq != null ? hq.optString("country") : ""));
}
Thread.sleep(500);
}
Files.writeString(Path.of("enriched_leads.json"), enriched.toString(2));
System.out.println("Enriched " + enriched.length() + " leads → enriched_leads.json");
}
}
```
</Tab>
<Tab value="C#">
```csharp
using System.Net.Http;
using System.Text.Json;
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");
var leads = new[] {
(email: "alice@stripe.com", domain: "stripe.com"),
(email: "bob@notion.so", domain: "notion.so"),
(email: "carol@figma.com", domain: "figma.com"),
};
var enriched = new List<object>();
foreach (var lead in leads)
{
var resp = await client.GetAsync(
$"https://api.piloterr.com/v2/linkedin/company/info?domain={lead.domain}");
if (resp.IsSuccessStatusCode)
{
var c = JsonDocument.Parse(await resp.Content.ReadAsStringAsync()).RootElement;
var hq = c.GetProperty("headquarter");
enriched.Add(new {
email = lead.email, domain = lead.domain,
company = c.GetProperty("company_name").GetString(),
industry = c.GetProperty("industry").GetString(),
employees = c.GetProperty("staff_count").GetInt32(),
hq_country = hq.GetProperty("country").GetString(),
});
}
await Task.Delay(500);
}
File.WriteAllText("enriched_leads.json",
JsonSerializer.Serialize(enriched, new JsonSerializerOptions { WriteIndented = true }));
Console.WriteLine($"Enriched {enriched.Count} leads → enriched_leads.json");
```
</Tab>
<Tab value="Rust">
```rust
use reqwest::Client;
use serde_json::{json, Value};
use std::{fs, time::Duration};
use tokio::time::sleep;
#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
let client = Client::new();
let api_key = "YOUR_API_KEY";
let leads = vec![("alice@stripe.com", "stripe.com"), ("bob@notion.so", "notion.so"), ("carol@figma.com", "figma.com")];
let mut enriched: Vec<Value> = Vec::new();
for (email, domain) in &leads {
let c = client.get("https://api.piloterr.com/v2/linkedin/company/info")
.header("x-api-key", api_key).query(&[("domain", domain)])
.send().await?.json::<Value>().await?;
enriched.push(json!({
"email": email, "domain": domain,
"company": c["company_name"], "industry": c["industry"],
"employees": c["staff_count"], "hq_country": c["headquarter"]["country"],
}));
sleep(Duration::from_millis(500)).await;
}
fs::write("enriched_leads.json", serde_json::to_string_pretty(&enriched).unwrap()).unwrap();
println!("Enriched {} leads → enriched_leads.json", enriched.len());
Ok(())
}
```
</Tab>
</Tabs>
</Step>
</Steps>
<Callout type="info">
You can also pass a LinkedIn company URL or username to the `query` parameter instead of a domain — useful when you already have the LinkedIn URL from a scrape or manual research.
</Callout>
# Crawl Any Website (/playbooks/piloterr-website-crawler)
## Overview [#overview]
This playbook shows how to fetch the full HTML of any webpage using the Piloterr Website Crawler, then extract specific data from it. A typical use case is **competitor price monitoring**: crawl a product page daily and parse the price from the HTML.
## Prerequisites [#prerequisites]
* A Piloterr API key — get one at [app.piloterr.com](https://app.piloterr.com)
* Install dependencies for your language:
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```bash
pip install requests beautifulsoup4
```
</Tab>
<Tab value="TypeScript">
```bash
npm install node-html-parser
```
</Tab>
<Tab value="PHP">
`curl` and `DOMDocument` extensions (both enabled by default).
</Tab>
<Tab value="Go">
No extra dependencies for the request — uses `net/http` (Go 1.18+). Add `golang.org/x/net/html` for parsing.
</Tab>
<Tab value="Java">
No extra dependencies for the request — uses `java.net.http` (Java 11+). Add `org.jsoup:jsoup` for parsing.
</Tab>
<Tab value="C#">
No extra dependencies for the request — uses `System.Net.Http` (.NET 6+). Add `HtmlAgilityPack` for parsing.
</Tab>
<Tab value="Rust">
```toml
# Cargo.toml
[dependencies]
reqwest = { version = "0.12", features = ["json"] }
tokio = { version = "1", features = ["full"] }
serde_json = "1"
```
</Tab>
</Tabs>
## Steps [#steps]
<Steps>
<Step>
### Crawl a webpage [#crawl-a-webpage]
Call `GET /v2/website/crawler` with the `query` parameter set to the target URL. The response is the raw HTML string (JSON-encoded).
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```python
import requests
API_KEY = "YOUR_API_KEY"
response = requests.get(
"https://api.piloterr.com/v2/website/crawler",
headers={"x-api-key": API_KEY},
params={"query": "https://example.com", "allow_redirects": "true"},
)
html = response.json() # returns the HTML as a string
print(html[:500])
```
</Tab>
<Tab value="TypeScript">
```typescript
const API_KEY = "YOUR_API_KEY";
const params = new URLSearchParams({ query: "https://example.com", allow_redirects: "true" });
const response = await fetch(`https://api.piloterr.com/v2/website/crawler?${params}`, {
headers: { "x-api-key": API_KEY },
});
const html: string = await response.json();
console.log(html.slice(0, 500));
```
</Tab>
<Tab value="PHP">
```php
<?php
$apiKey = "YOUR_API_KEY";
$params = http_build_query(["query" => "https://example.com", "allow_redirects" => "true"]);
$ch = curl_init("https://api.piloterr.com/v2/website/crawler?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]);
$html = json_decode(curl_exec($ch), true); // HTML string
curl_close($ch);
echo substr($html, 0, 500);
```
</Tab>
<Tab value="Go">
```go
package main
import (
"encoding/json"
"fmt"
"io"
"net/http"
"net/url"
)
func main() {
params := url.Values{"query": {"https://example.com"}, "allow_redirects": {"true"}}
req, _ := http.NewRequest("GET", "https://api.piloterr.com/v2/website/crawler?"+params.Encode(), nil)
req.Header.Set("x-api-key", "YOUR_API_KEY")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var html string
json.Unmarshal(body, &html) // response is a JSON-encoded string
fmt.Println(html[:500])
}
```
</Tab>
<Tab value="Java">
```java
import java.net.URI;
import java.net.http.*;
var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://api.piloterr.com/v2/website/crawler?query=https%3A%2F%2Fexample.com&allow_redirects=true"))
.header("x-api-key", "YOUR_API_KEY")
.GET().build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
// Response body is a JSON-encoded string — strip the outer quotes
var html = response.body().replaceAll("^\"|\"$", "")
.replace("\\n", "\n").replace("\\\"", "\"");
System.out.println(html.substring(0, Math.min(500, html.length())));
```
</Tab>
<Tab value="C#">
```csharp
using System.Net.Http;
using System.Text.Json;
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");
var raw = await client.GetStringAsync(
"https://api.piloterr.com/v2/website/crawler?query=https%3A%2F%2Fexample.com&allow_redirects=true");
var html = JsonSerializer.Deserialize<string>(raw)!; // response is JSON-encoded string
Console.WriteLine(html[..Math.Min(500, html.Length)]);
```
</Tab>
<Tab value="Rust">
```rust
#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
let html = reqwest::Client::new()
.get("https://api.piloterr.com/v2/website/crawler")
.header("x-api-key", "YOUR_API_KEY")
.query(&[("query", "https://example.com"), ("allow_redirects", "true")])
.send().await?
.json::<String>().await?;
println!("{}", &html[..500.min(html.len())]);
Ok(())
}
```
</Tab>
</Tabs>
</Step>
<Step>
### Extract data from the HTML [#extract-data-from-the-html]
Parse the HTML to extract specific elements — here we extract the page title and all `<h1>` headings.
<Tabs items="["Python", "TypeScript", "PHP", "Go", "Java", "C#", "Rust"]">
<Tab value="Python">
```python
from bs4 import BeautifulSoup
soup = BeautifulSoup(html, "html.parser")
title = soup.find("title")
print("Page title:", title.text if title else "N/A")
for h in soup.find_all("h1"):
print("H1:", h.get_text(strip=True))
```
</Tab>
<Tab value="TypeScript">
```typescript
import { parse } from "node-html-parser";
const root = parse(html);
const title = root.querySelector("title");
console.log("Page title:", title?.text ?? "N/A");
for (const h of root.querySelectorAll("h1")) {
console.log("H1:", h.text.trim());
}
```
</Tab>
<Tab value="PHP">
```php
$dom = new DOMDocument();
@$dom->loadHTML($html);
$xpath = new DOMXPath($dom);
$title = $xpath->query("//title")->item(0);
echo "Page title: " . ($title ? $title->textContent : "N/A") . "\n";
foreach ($xpath->query("//h1") as $h) {
echo "H1: " . trim($h->textContent) . "\n";
}
```
</Tab>
<Tab value="Go">
```go
import (
"fmt"
"strings"
"golang.org/x/net/html"
)
doc, _ := html.Parse(strings.NewReader(html))
var traverse func(*html.Node)
traverse = func(n *html.Node) {
if n.Type == html.ElementNode && n.Data == "title" && n.FirstChild != nil {
fmt.Println("Page title:", n.FirstChild.Data)
}
if n.Type == html.ElementNode && n.Data == "h1" && n.FirstChild != nil {
fmt.Println("H1:", n.FirstChild.Data)
}
for c := n.FirstChild; c != nil; c = c.NextSibling { traverse(c) }
}
traverse(doc)
```
</Tab>
<Tab value="Java">
```java
import org.jsoup.Jsoup;
var doc = Jsoup.parse(html);
System.out.println("Page title: " + doc.title());
doc.select("h1").forEach(h -> System.out.println("H1: " + h.text()));
```
</Tab>
<Tab value="C#">
```csharp
using HtmlAgilityPack;
var doc = new HtmlDocument();
doc.LoadHtml(html);
var title = doc.DocumentNode.SelectSingleNode("//title");
Console.WriteLine($"Page title: {title?.InnerText ?? "N/A"}");
foreach (var h in doc.DocumentNode.SelectNodes("//h1") ?? Enumerable.Empty<HtmlNode>())
Console.WriteLine($"H1: {h.InnerText.Trim()}");
```
</Tab>
<Tab value="Rust">
```rust
// Minimal regex-based extraction
use regex::Regex; // add regex = "1" to Cargo.toml
let title_re = Regex::new(r"<title[^>]*>(.*?)").unwrap();
if let Some(cap) = title_re.captures(&html) { println!("Page title: {}", &cap[1]); }
let h1_re = Regex::new(r"]*>(.*?)").unwrap();
for cap in h1_re.captures_iter(&html) { println!("H1: {}", &cap[1]); }
```
### Build a price monitoring script [#build-a-price-monitoring-script]
Crawl a product page and extract the price using a CSS selector.
```python
import requests
from bs4 import BeautifulSoup
API_KEY = "YOUR_API_KEY"
WATCH_URL = "https://www.example-shop.com/product/123"
def crawl(url: str) -> str:
r = requests.get("https://api.piloterr.com/v2/website/crawler",
headers={"x-api-key": API_KEY}, params={"query": url, "allow_redirects": "true"})
return r.json()
def extract_price(html: str) -> str | None:
soup = BeautifulSoup(html, "html.parser")
el = soup.select_one("[data-price], .price, #price")
return el.get_text(strip=True) if el else None
price = extract_price(crawl(WATCH_URL))
print(f"Current price: {price}" if price else "Price element not found.")
```
```typescript
import { parse } from "node-html-parser";
const API_KEY = "YOUR_API_KEY";
const WATCH_URL = "https://www.example-shop.com/product/123";
async function crawl(url: string): Promise {
const params = new URLSearchParams({ query: url, allow_redirects: "true" });
const res = await fetch(`https://api.piloterr.com/v2/website/crawler?${params}`, {
headers: { "x-api-key": API_KEY },
});
return res.json();
}
const html = await crawl(WATCH_URL);
const root = parse(html);
const price = root.querySelector("[data-price], .price, #price")?.text.trim() ?? null;
console.log(price ? `Current price: ${price}` : "Price element not found.");
```
```php
$url, "allow_redirects" => "true"]);
$ch = curl_init("https://api.piloterr.com/v2/website/crawler?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]);
$html = json_decode(curl_exec($ch), true);
curl_close($ch);
return $html;
}
$html = crawl("YOUR_API_KEY", "https://www.example-shop.com/product/123");
$dom = new DOMDocument();
@$dom->loadHTML($html);
$xpath = new DOMXPath($dom);
$price = null;
foreach (["//span[@class='price']", "//*[@id='price']", "//*[@data-price]"] as $sel) {
$nodes = $xpath->query($sel);
if ($nodes->length > 0) { $price = trim($nodes->item(0)->textContent); break; }
}
echo $price ? "Current price: {$price}\n" : "Price element not found.\n";
```
```go
package main
import (
"encoding/json"
"fmt"
"io"
"net/http"
"net/url"
"regexp"
)
func crawl(apiKey, pageUrl string) string {
params := url.Values{"query": {pageUrl}, "allow_redirects": {"true"}}
req, _ := http.NewRequest("GET", "https://api.piloterr.com/v2/website/crawler?"+params.Encode(), nil)
req.Header.Set("x-api-key", apiKey)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var html string
json.Unmarshal(body, &html)
return html
}
func main() {
html := crawl("YOUR_API_KEY", "https://www.example-shop.com/product/123")
re := regexp.MustCompile(`class="price[^"]*"[^>]*>([^<]+)`)
match := re.FindStringSubmatch(html)
if match != nil {
fmt.Println("Current price:", match[1])
} else {
fmt.Println("Price element not found.")
}
}
```
```java
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
import org.jsoup.Jsoup;
public class Main {
public static void main(String[] args) throws Exception {
var apiKey = "YOUR_API_KEY";
var watchUrl = URLEncoder.encode("https://www.example-shop.com/product/123", StandardCharsets.UTF_8);
var url = "https://api.piloterr.com/v2/website/crawler?query=" + watchUrl + "&allow_redirects=true";
var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder().uri(URI.create(url))
.header("x-api-key", apiKey).GET().build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
// Strip JSON string quotes
var html = response.body().replaceAll("^\"|\"$", "").replace("\\\"", "\"").replace("\\n", "\n");
var doc = Jsoup.parse(html);
var priceEl = doc.selectFirst(".price, #price, [data-price]");
System.out.println(priceEl != null ? "Current price: " + priceEl.text() : "Price element not found.");
}
}
```
```csharp
using System.Net.Http;
using System.Text.Json;
using HtmlAgilityPack;
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");
var watchUrl = Uri.EscapeDataString("https://www.example-shop.com/product/123");
var raw = await client.GetStringAsync(
$"https://api.piloterr.com/v2/website/crawler?query={watchUrl}&allow_redirects=true");
var html = JsonSerializer.Deserialize(raw)!;
var doc = new HtmlDocument();
doc.LoadHtml(html);
var price = doc.DocumentNode.SelectSingleNode("//*[contains(@class,'price') or @id='price' or @data-price]");
Console.WriteLine(price != null ? $"Current price: {price.InnerText.Trim()}" : "Price element not found.");
```
```rust
use reqwest::Client;
use regex::Regex;
async fn crawl(client: &Client, api_key: &str, url: &str) -> String {
client.get("https://api.piloterr.com/v2/website/crawler")
.header("x-api-key", api_key)
.query(&[("query", url), ("allow_redirects", "true")])
.send().await.unwrap().json::().await.unwrap()
}
#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
let client = Client::new();
let html = crawl(&client, "YOUR_API_KEY", "https://www.example-shop.com/product/123").await;
let re = Regex::new(r#"class="price[^"]*"[^>]*>([^<]+)"#).unwrap();
match re.captures(&html) {
Some(cap) => println!("Current price: {}", cap[1].trim()),
None => println!("Price element not found."),
}
Ok(())
}
```
Set `allow_redirects=true` to follow HTTP 301/302 redirects automatically — useful for short URLs or e-commerce platforms that redirect product pages.
# Detect Disposable Domains (/playbooks/veille-domain-validation)
## Overview [#overview]
Disposable email providers let users create temporary inboxes that get deleted after minutes or days. This playbook shows how to query the Veille domain validation endpoint and use the result to block or flag signups at the point of registration.
## Prerequisites [#prerequisites]
* A Veille API key — get one at [app.veille.io](https://app.veille.io)
* Install dependencies for your language:
```bash
pip install requests
```
No extra dependencies — uses the native `fetch` API (Node 18+).
`curl` extension enabled (on by default).
No extra dependencies — uses `net/http` (Go 1.18+).
No extra dependencies — uses `java.net.http` (Java 11+).
No extra dependencies — uses `System.Net.Http` (.NET 6+).
```toml
# Cargo.toml
[dependencies]
reqwest = { version = "0.12", features = ["json"] }
tokio = { version = "1", features = ["full"] }
serde_json = "1"
```
## Steps [#steps]
### Check a domain [#check-a-domain]
Call `GET /v1/domain` with the `domain` parameter. The response returns whether it is disposable, free, or a custom domain.
```python
import requests
API_KEY = "YOUR_API_KEY"
response = requests.get(
"https://api.veille.io/v1/domain",
headers={"x-api-key": API_KEY},
params={"domain": "mailinator.com"},
)
result = response.json()
print(result)
```
```typescript
const API_KEY = "YOUR_API_KEY";
const params = new URLSearchParams({ domain: "mailinator.com" });
const response = await fetch(`https://api.veille.io/v1/domain?${params}`, {
headers: { "x-api-key": API_KEY },
});
const result = await response.json();
console.log(result);
```
```php
"mailinator.com"]);
$ch = curl_init("https://api.veille.io/v1/domain?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($result);
```
```go
package main
import (
"encoding/json"
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://api.veille.io/v1/domain?domain=mailinator.com", nil)
req.Header.Set("x-api-key", "YOUR_API_KEY")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var result map[string]any
json.Unmarshal(body, &result)
fmt.Println(result)
}
```
```java
import java.net.URI;
import java.net.http.*;
var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://api.veille.io/v1/domain?domain=mailinator.com"))
.header("x-api-key", "YOUR_API_KEY")
.GET().build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```
```csharp
using System.Net.Http;
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");
var body = await client.GetStringAsync("https://api.veille.io/v1/domain?domain=mailinator.com");
Console.WriteLine(body);
```
```rust
#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
let result = reqwest::Client::new()
.get("https://api.veille.io/v1/domain")
.header("x-api-key", "YOUR_API_KEY")
.query(&[("domain", "mailinator.com")])
.send().await?.json::().await?;
println!("{:#?}", result);
Ok(())
}
```
### Read the response fields [#read-the-response-fields]
The response includes `is_disposable`, `is_free`, `is_custom`, `domain`, and `provider` (when identified).
```python
domain = result.get("domain")
is_disposable = result.get("is_disposable")
is_free = result.get("is_free")
provider = result.get("provider", "unknown")
if is_disposable:
print(f"❌ {domain} is a DISPOSABLE email provider ({provider}). Block this signup.")
elif is_free:
print(f"⚠️ {domain} is a free email provider. Consider extra verification.")
else:
print(f"✅ {domain} looks like a custom / business domain. Allow.")
```
```typescript
const { domain, is_disposable, is_free, provider } = result;
if (is_disposable) {
console.log(`❌ ${domain} is DISPOSABLE (${provider ?? "unknown"}). Block this signup.`);
} else if (is_free) {
console.log(`⚠️ ${domain} is a free provider. Consider extra verification.`);
} else {
console.log(`✅ ${domain} looks like a business domain. Allow.`);
}
```
```php
$domain = $result["domain"] ?? "";
$isDisposable = $result["is_disposable"] ?? false;
$isFree = $result["is_free"] ?? false;
$provider = $result["provider"] ?? "unknown";
if ($isDisposable) {
echo "❌ {$domain} is DISPOSABLE ({$provider}). Block this signup.\n";
} elseif ($isFree) {
echo "⚠️ {$domain} is free. Consider extra verification.\n";
} else {
echo "✅ {$domain} looks like a business domain. Allow.\n";
}
```
```go
domain := result["domain"].(string)
isDisposable := result["is_disposable"].(bool)
isFree := result["is_free"].(bool)
provider, _ := result["provider"].(string)
switch {
case isDisposable:
fmt.Printf("❌ %s is DISPOSABLE (%s). Block this signup.\n", domain, provider)
case isFree:
fmt.Printf("⚠️ %s is a free provider.\n", domain)
default:
fmt.Printf("✅ %s is a business domain. Allow.\n", domain)
}
```
```java
import org.json.*;
var r = new JSONObject(response.body());
var domain = r.getString("domain");
var isDisposable = r.getBoolean("is_disposable");
var isFree = r.getBoolean("is_free");
var provider = r.optString("provider", "unknown");
if (isDisposable) System.out.printf("❌ %s is DISPOSABLE (%s). Block.%n", domain, provider);
else if (isFree) System.out.printf("⚠️ %s is free. Extra verification.%n", domain);
else System.out.printf("✅ %s is a business domain. Allow.%n", domain);
```
```csharp
using System.Text.Json;
var r = JsonDocument.Parse(body).RootElement;
var domain = r.GetProperty("domain").GetString();
var isDisposable = r.GetProperty("is_disposable").GetBoolean();
var isFree = r.GetProperty("is_free").GetBoolean();
var provider = r.TryGetProperty("provider", out var p) ? p.GetString() : "unknown";
if (isDisposable)
Console.WriteLine($"❌ {domain} is DISPOSABLE ({provider}). Block.");
else if (isFree)
Console.WriteLine($"⚠️ {domain} is free. Extra verification.");
else
Console.WriteLine($"✅ {domain} is a business domain. Allow.");
```
```rust
let domain = result["domain"].as_str().unwrap_or("");
let is_disposable = result["is_disposable"].as_bool().unwrap_or(false);
let is_free = result["is_free"].as_bool().unwrap_or(false);
let provider = result["provider"].as_str().unwrap_or("unknown");
if is_disposable {
println!("❌ {} is DISPOSABLE ({}). Block.", domain, provider);
} else if is_free {
println!("⚠️ {} is free. Extra verification.", domain);
} else {
println!("✅ {} is a business domain. Allow.", domain);
}
```
### Integrate into a signup handler [#integrate-into-a-signup-handler]
Add the domain check to your registration endpoint and return a validation error before the user record is created.
```python
import requests
API_KEY = "YOUR_API_KEY"
def is_disposable_email(email: str) -> bool:
domain = email.split("@")[-1].lower()
r = requests.get("https://api.veille.io/v1/domain",
headers={"x-api-key": API_KEY}, params={"domain": domain})
return r.json().get("is_disposable", False)
def register_user(email: str, password: str) -> dict:
if is_disposable_email(email):
return {"success": False, "error": "Disposable email addresses are not allowed."}
# ... create the user record in your database
return {"success": True, "message": f"Welcome, {email}!"}
print(register_user("alice@mailinator.com", "secret"))
print(register_user("alice@company.com", "secret"))
```
```typescript
const API_KEY = "YOUR_API_KEY";
async function isDisposableEmail(email: string): Promise {
const domain = email.split("@").at(-1)!.toLowerCase();
const params = new URLSearchParams({ domain });
const res = await fetch(`https://api.veille.io/v1/domain?${params}`, {
headers: { "x-api-key": API_KEY },
});
return (await res.json()).is_disposable ?? false;
}
async function registerUser(email: string, password: string) {
if (await isDisposableEmail(email)) {
return { success: false, error: "Disposable email addresses are not allowed." };
}
// ... create user record
return { success: true, message: `Welcome, ${email}!` };
}
console.log(await registerUser("alice@mailinator.com", "secret"));
console.log(await registerUser("alice@company.com", "secret"));
```
```php
$domain]);
$ch = curl_init("https://api.veille.io/v1/domain?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
return $result["is_disposable"] ?? false;
}
function registerUser(string $apiKey, string $email, string $password): array {
if (isDisposableEmail($apiKey, $email)) {
return ["success" => false, "error" => "Disposable email addresses are not allowed."];
}
// ... create user record
return ["success" => true, "message" => "Welcome, {$email}!"];
}
print_r(registerUser("YOUR_API_KEY", "alice@mailinator.com", "secret"));
print_r(registerUser("YOUR_API_KEY", "alice@company.com", "secret"));
```
```go
package main
import (
"encoding/json"
"fmt"
"io"
"net/http"
"strings"
)
func isDisposable(apiKey, email string) bool {
domain := strings.ToLower(strings.SplitN(email, "@", 2)[1])
req, _ := http.NewRequest("GET", "https://api.veille.io/v1/domain?domain="+domain, nil)
req.Header.Set("x-api-key", apiKey)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var result map[string]any
json.Unmarshal(body, &result)
v, _ := result["is_disposable"].(bool)
return v
}
func registerUser(apiKey, email, password string) string {
if isDisposable(apiKey, email) {
return "❌ Disposable email not allowed."
}
return "✅ Welcome, " + email + "!"
}
func main() {
apiKey := "YOUR_API_KEY"
fmt.Println(registerUser(apiKey, "alice@mailinator.com", "secret"))
fmt.Println(registerUser(apiKey, "alice@company.com", "secret"))
}
```
```java
import java.net.URI;
import java.net.http.*;
import org.json.*;
public class Main {
static HttpClient client = HttpClient.newHttpClient();
static String API_KEY = "YOUR_API_KEY";
static boolean isDisposable(String email) throws Exception {
var domain = email.substring(email.indexOf('@') + 1).toLowerCase();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://api.veille.io/v1/domain?domain=" + domain))
.header("x-api-key", API_KEY).GET().build();
var resp = client.send(request, HttpResponse.BodyHandlers.ofString());
return new JSONObject(resp.body()).optBoolean("is_disposable", false);
}
static String registerUser(String email, String password) throws Exception {
if (isDisposable(email)) return "❌ Disposable email not allowed.";
return "✅ Welcome, " + email + "!";
}
public static void main(String[] args) throws Exception {
System.out.println(registerUser("alice@mailinator.com", "secret"));
System.out.println(registerUser("alice@company.com", "secret"));
}
}
```
```csharp
using System.Net.Http;
using System.Text.Json;
var apiKey = "YOUR_API_KEY";
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", apiKey);
async Task IsDisposable(string email)
{
var domain = email.Split('@').Last().ToLower();
var body = await client.GetStringAsync($"https://api.veille.io/v1/domain?domain={domain}");
return JsonDocument.Parse(body).RootElement.GetProperty("is_disposable").GetBoolean();
}
async Task RegisterUser(string email, string password) =>
await IsDisposable(email)
? "❌ Disposable email not allowed."
: $"✅ Welcome, {email}!";
Console.WriteLine(await RegisterUser("alice@mailinator.com", "secret"));
Console.WriteLine(await RegisterUser("alice@company.com", "secret"));
```
```rust
use reqwest::Client;
use serde_json::Value;
async fn is_disposable(client: &Client, api_key: &str, email: &str) -> bool {
let domain = email.split('@').last().unwrap_or("").to_lowercase();
let result = client.get("https://api.veille.io/v1/domain")
.header("x-api-key", api_key)
.query(&[("domain", domain.as_str())])
.send().await.unwrap().json::().await.unwrap();
result["is_disposable"].as_bool().unwrap_or(false)
}
#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
let client = Client::new();
let api_key = "YOUR_API_KEY";
for email in ["alice@mailinator.com", "alice@company.com"] {
if is_disposable(&client, api_key, email).await {
println!("❌ {} — disposable. Block.", email);
} else {
println!("✅ {} — looks valid. Allow.", email);
}
}
Ok(())
}
```
Cache results for frequently checked domains (e.g. in Redis with a 24-hour TTL) to avoid redundant API calls. The list of disposable providers rarely changes within a single day.
# Validate Email on Signup (/playbooks/veille-email-validation)
## Overview [#overview]
This playbook shows how to run a full email validation before accepting a signup: syntax check, DNS/MX record lookup, and SMTP reachability. The API returns a `risk_score` (0 = clean, 100 = high risk) that you can use to route users to extra verification steps.
## Prerequisites [#prerequisites]
* A Veille API key — get one at [app.veille.io](https://app.veille.io)
* Install dependencies for your language:
```bash
pip install requests
```
No extra dependencies — uses the native `fetch` API (Node 18+).
`curl` extension enabled (on by default).
No extra dependencies — uses `net/http` (Go 1.18+).
No extra dependencies — uses `java.net.http` (Java 11+).
No extra dependencies — uses `System.Net.Http` (.NET 6+).
```toml
# Cargo.toml
[dependencies]
reqwest = { version = "0.12", features = ["json"] }
tokio = { version = "1", features = ["full"] }
serde_json = "1"
```
## Steps [#steps]
### Validate an email address [#validate-an-email-address]
Call `GET /v1/email` with the `email` parameter.
```python
import requests
API_KEY = "YOUR_API_KEY"
response = requests.get(
"https://api.veille.io/v1/email",
headers={"x-api-key": API_KEY},
params={"email": "alice@example.com"},
)
result = response.json()
print(result)
```
```typescript
const API_KEY = "YOUR_API_KEY";
const params = new URLSearchParams({ email: "alice@example.com" });
const response = await fetch(`https://api.veille.io/v1/email?${params}`, {
headers: { "x-api-key": API_KEY },
});
const result = await response.json();
console.log(result);
```
```php
"alice@example.com"]);
$ch = curl_init("https://api.veille.io/v1/email?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($result);
```
```go
package main
import (
"encoding/json"
"fmt"
"io"
"net/http"
"net/url"
)
func main() {
params := url.Values{"email": {"alice@example.com"}}
req, _ := http.NewRequest("GET", "https://api.veille.io/v1/email?"+params.Encode(), nil)
req.Header.Set("x-api-key", "YOUR_API_KEY")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var result map[string]any
json.Unmarshal(body, &result)
fmt.Println(result)
}
```
```java
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
var client = HttpClient.newHttpClient();
var email = URLEncoder.encode("alice@example.com", StandardCharsets.UTF_8);
var request = HttpRequest.newBuilder()
.uri(URI.create("https://api.veille.io/v1/email?email=" + email))
.header("x-api-key", "YOUR_API_KEY")
.GET().build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```
```csharp
using System.Net.Http;
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");
var email = Uri.EscapeDataString("alice@example.com");
var body = await client.GetStringAsync($"https://api.veille.io/v1/email?email={email}");
Console.WriteLine(body);
```
```rust
#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
let result = reqwest::Client::new()
.get("https://api.veille.io/v1/email")
.header("x-api-key", "YOUR_API_KEY")
.query(&[("email", "alice@example.com")])
.send().await?.json::().await?;
println!("{:#?}", result);
Ok(())
}
```
### Interpret the result [#interpret-the-result]
Key fields: `is_valid`, `is_deliverable`, `is_disposable`, `is_role_account`, `risk_score`, `did_you_mean` (typo suggestion).
```python
print(f"Valid : {result['is_valid']}")
print(f"Deliverable : {result['is_deliverable']}")
print(f"Disposable : {result['is_disposable']}")
print(f"Role account: {result['is_role_account']}")
print(f"Risk score : {result['risk_score']}/100")
if result.get("did_you_mean"):
print(f"Did you mean: {result['did_you_mean']}?")
```
```typescript
console.log(`Valid : ${result.is_valid}`);
console.log(`Deliverable : ${result.is_deliverable}`);
console.log(`Disposable : ${result.is_disposable}`);
console.log(`Role account: ${result.is_role_account}`);
console.log(`Risk score : ${result.risk_score}/100`);
if (result.did_you_mean) console.log(`Did you mean: ${result.did_you_mean}?`);
```
```php
echo "Valid : " . ($result["is_valid"] ? "true" : "false") . "\n";
echo "Deliverable : " . ($result["is_deliverable"] ? "true" : "false") . "\n";
echo "Disposable : " . ($result["is_disposable"] ? "true" : "false") . "\n";
echo "Risk score : {$result['risk_score']}/100\n";
if (!empty($result["did_you_mean"])) echo "Did you mean: {$result['did_you_mean']}?\n";
```
```go
fmt.Printf("Valid : %v\nDeliverable : %v\nDisposable : %v\nRisk score : %v/100\n",
result["is_valid"], result["is_deliverable"], result["is_disposable"], result["risk_score"])
if typo, ok := result["did_you_mean"].(string); ok && typo != "" {
fmt.Println("Did you mean:", typo+"?")
}
```
```java
import org.json.*;
var r = new JSONObject(response.body());
System.out.printf("Valid : %b%nDeliverable : %b%nDisposable : %b%nRisk score : %d/100%n",
r.getBoolean("is_valid"), r.getBoolean("is_deliverable"),
r.getBoolean("is_disposable"), r.getInt("risk_score"));
if (r.has("did_you_mean")) System.out.println("Did you mean: " + r.getString("did_you_mean") + "?");
```
```csharp
using System.Text.Json;
var r = JsonDocument.Parse(body).RootElement;
Console.WriteLine($"Valid : {r.GetProperty("is_valid").GetBoolean()}");
Console.WriteLine($"Deliverable : {r.GetProperty("is_deliverable").GetBoolean()}");
Console.WriteLine($"Disposable : {r.GetProperty("is_disposable").GetBoolean()}");
Console.WriteLine($"Risk score : {r.GetProperty("risk_score").GetInt32()}/100");
if (r.TryGetProperty("did_you_mean", out var typo) && typo.GetString() is { } t and not "")
Console.WriteLine($"Did you mean: {t}?");
```
```rust
println!("Valid : {}", result["is_valid"]);
println!("Deliverable : {}", result["is_deliverable"]);
println!("Disposable : {}", result["is_disposable"]);
println!("Risk score : {}/100", result["risk_score"]);
if let Some(typo) = result["did_you_mean"].as_str() {
if !typo.is_empty() { println!("Did you mean: {}?", typo); }
}
```
### Build a risk-tiered registration flow [#build-a-risk-tiered-registration-flow]
Use `risk_score` to route users: block high-risk addresses, prompt typo corrections, and apply extra friction to role accounts.
```python
import requests
API_KEY = "YOUR_API_KEY"
def validate_email(email: str) -> dict:
r = requests.get("https://api.veille.io/v1/email",
headers={"x-api-key": API_KEY}, params={"email": email})
return r.json()
def register(email: str) -> dict:
v = validate_email(email)
if not v.get("is_valid"):
return {"ok": False, "error": "This email address is invalid."}
if v.get("is_disposable"):
return {"ok": False, "error": "Temporary email addresses are not accepted."}
if v.get("did_you_mean"):
return {"ok": False, "suggestion": f"Did you mean {v['did_you_mean']}?"}
if v.get("risk_score", 0) >= 70:
return {"ok": False, "error": "This email has a high risk score. Please use a different address."}
if v.get("is_role_account"):
# Allow but flag for manual review
return {"ok": True, "flag": "role_account", "message": "Please verify your email."}
return {"ok": True, "message": "Registration successful!"}
for test_email in ["alice@mailinator.com", "info@company.com", "alice@gmial.com", "alice@stripe.com"]:
print(f"{test_email}: {register(test_email)}")
```
```typescript
const API_KEY = "YOUR_API_KEY";
async function validateEmail(email: string) {
const params = new URLSearchParams({ email });
const res = await fetch(`https://api.veille.io/v1/email?${params}`, {
headers: { "x-api-key": API_KEY },
});
return res.json();
}
async function register(email: string) {
const v = await validateEmail(email);
if (!v.is_valid) return { ok: false, error: "Invalid email address." };
if (v.is_disposable) return { ok: false, error: "Temporary emails not accepted." };
if (v.did_you_mean) return { ok: false, suggestion: `Did you mean ${v.did_you_mean}?` };
if (v.risk_score >= 70) return { ok: false, error: "High risk score — please use another address." };
if (v.is_role_account) return { ok: true, flag: "role_account", message: "Please verify your email." };
return { ok: true, message: "Registration successful!" };
}
for (const email of ["alice@mailinator.com", "info@company.com", "alice@gmial.com", "alice@stripe.com"]) {
console.log(email, await register(email));
}
```
```php
$email]);
$ch = curl_init("https://api.veille.io/v1/email?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
return $result;
}
function register(string $apiKey, string $email): array {
$v = validateEmail($apiKey, $email);
if (!($v["is_valid"] ?? false)) return ["ok" => false, "error" => "Invalid email."];
if ($v["is_disposable"] ?? false) return ["ok" => false, "error" => "Temporary emails not accepted."];
if (!empty($v["did_you_mean"])) return ["ok" => false, "suggestion" => "Did you mean {$v['did_you_mean']}?"];
if (($v["risk_score"] ?? 0) >= 70) return ["ok" => false, "error" => "High risk score."];
if ($v["is_role_account"] ?? false) return ["ok" => true, "flag" => "role_account"];
return ["ok" => true, "message" => "Registration successful!"];
}
foreach (["alice@mailinator.com", "info@company.com", "alice@gmial.com"] as $email) {
print_r(["email" => $email, "result" => register("YOUR_API_KEY", $email)]);
}
```
```go
package main
import (
"encoding/json"
"fmt"
"io"
"net/http"
"net/url"
)
const APIKey = "YOUR_API_KEY"
func validate(email string) map[string]any {
params := url.Values{"email": {email}}
req, _ := http.NewRequest("GET", "https://api.veille.io/v1/email?"+params.Encode(), nil)
req.Header.Set("x-api-key", APIKey)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var v map[string]any
json.Unmarshal(body, &v)
return v
}
func register(email string) string {
v := validate(email)
if !(v["is_valid"].(bool)) { return "❌ Invalid email." }
if v["is_disposable"].(bool) { return "❌ Disposable not accepted." }
if typo, ok := v["did_you_mean"].(string); ok && typo != "" {
return "⚠️ Did you mean " + typo + "?"
}
if v["risk_score"].(float64) >= 70 { return "❌ High risk score." }
return "✅ Registration successful!"
}
func main() {
for _, email := range []string{"alice@mailinator.com", "info@company.com", "alice@stripe.com"} {
fmt.Printf("%s: %s\n", email, register(email))
}
}
```
```java
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
import org.json.*;
public class Main {
static HttpClient client = HttpClient.newHttpClient();
static String API_KEY = "YOUR_API_KEY";
static JSONObject validate(String email) throws Exception {
var encoded = URLEncoder.encode(email, StandardCharsets.UTF_8);
var req = HttpRequest.newBuilder()
.uri(URI.create("https://api.veille.io/v1/email?email=" + encoded))
.header("x-api-key", API_KEY).GET().build();
var resp = client.send(req, HttpResponse.BodyHandlers.ofString());
return new JSONObject(resp.body());
}
static String register(String email) throws Exception {
var v = validate(email);
if (!v.getBoolean("is_valid")) return "❌ Invalid email.";
if (v.getBoolean("is_disposable")) return "❌ Disposable not accepted.";
if (v.has("did_you_mean")) return "⚠️ Did you mean " + v.getString("did_you_mean") + "?";
if (v.getInt("risk_score") >= 70) return "❌ High risk score.";
return "✅ Registration successful!";
}
public static void main(String[] args) throws Exception {
for (var email : new String[]{"alice@mailinator.com", "info@company.com", "alice@stripe.com"}) {
System.out.printf("%s: %s%n", email, register(email));
}
}
}
```
```csharp
using System.Net.Http;
using System.Text.Json;
var apiKey = "YOUR_API_KEY";
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", apiKey);
async Task Validate(string email)
{
var encoded = Uri.EscapeDataString(email);
var body = await client.GetStringAsync($"https://api.veille.io/v1/email?email={encoded}");
return JsonDocument.Parse(body).RootElement;
}
async Task Register(string email)
{
var v = await Validate(email);
if (!v.GetProperty("is_valid").GetBoolean()) return "❌ Invalid email.";
if (v.GetProperty("is_disposable").GetBoolean()) return "❌ Disposable not accepted.";
if (v.TryGetProperty("did_you_mean", out var t) && t.GetString() is { Length: > 0 } typo)
return $"⚠️ Did you mean {typo}?";
if (v.GetProperty("risk_score").GetInt32() >= 70) return "❌ High risk score.";
return "✅ Registration successful!";
}
foreach (var email in new[] { "alice@mailinator.com", "info@company.com", "alice@stripe.com" })
Console.WriteLine($"{email}: {await Register(email)}");
```
```rust
use reqwest::Client;
use serde_json::Value;
const API_KEY: &str = "YOUR_API_KEY";
async fn validate(client: &Client, email: &str) -> Value {
client.get("https://api.veille.io/v1/email")
.header("x-api-key", API_KEY)
.query(&[("email", email)])
.send().await.unwrap().json::().await.unwrap()
}
async fn register(client: &Client, email: &str) -> &'static str {
let v = validate(client, email).await;
if !v["is_valid"].as_bool().unwrap_or(false) { return "❌ Invalid email."; }
if v["is_disposable"].as_bool().unwrap_or(false) { return "❌ Disposable not accepted."; }
if v["risk_score"].as_i64().unwrap_or(0) >= 70 { return "❌ High risk score."; }
"✅ Registration successful!"
}
#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
let client = Client::new();
for email in ["alice@mailinator.com", "info@company.com", "alice@stripe.com"] {
println!("{}: {}", email, register(&client, email).await);
}
Ok(())
}
```
Role accounts (`admin@`, `info@`, `support@`) are often monitored by multiple people — or not monitored at all. Flag them for manual review rather than blocking outright to avoid losing legitimate B2B signups.
# Validate EU VAT Numbers (/playbooks/veille-vat-validation)
## Overview [#overview]
EU businesses are exempt from VAT when purchasing from other EU businesses — but only with a valid VAT number. This playbook shows how to validate a VAT number at checkout and retrieve the associated company details (name and address) from the VIES database.
## Prerequisites [#prerequisites]
* A Veille API key — get one at [app.veille.io](https://app.veille.io)
* Install dependencies for your language:
```bash
pip install requests
```
No extra dependencies — uses the native `fetch` API (Node 18+).
`curl` extension enabled (on by default).
No extra dependencies — uses `net/http` (Go 1.18+).
No extra dependencies — uses `java.net.http` (Java 11+).
No extra dependencies — uses `System.Net.Http` (.NET 6+).
```toml
# Cargo.toml
[dependencies]
reqwest = { version = "0.12", features = ["json"] }
tokio = { version = "1", features = ["full"] }
serde_json = "1"
```
## Steps [#steps]
### Validate a VAT number [#validate-a-vat-number]
Call `GET /v1/vat` with the `vat` parameter. The number should include the country prefix (e.g. `FR12345678901`).
```python
import requests
API_KEY = "YOUR_API_KEY"
response = requests.get(
"https://api.veille.io/v1/vat",
headers={"x-api-key": API_KEY},
params={"vat": "FR12345678901"},
)
result = response.json()
print(result)
```
```typescript
const API_KEY = "YOUR_API_KEY";
const params = new URLSearchParams({ vat: "FR12345678901" });
const response = await fetch(`https://api.veille.io/v1/vat?${params}`, {
headers: { "x-api-key": API_KEY },
});
const result = await response.json();
console.log(result);
```
```php
"FR12345678901"]);
$ch = curl_init("https://api.veille.io/v1/vat?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($result);
```
```go
package main
import (
"encoding/json"
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://api.veille.io/v1/vat?vat=FR12345678901", nil)
req.Header.Set("x-api-key", "YOUR_API_KEY")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var result map[string]any
json.Unmarshal(body, &result)
fmt.Println(result)
}
```
```java
import java.net.URI;
import java.net.http.*;
var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://api.veille.io/v1/vat?vat=FR12345678901"))
.header("x-api-key", "YOUR_API_KEY")
.GET().build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```
```csharp
using System.Net.Http;
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");
var body = await client.GetStringAsync("https://api.veille.io/v1/vat?vat=FR12345678901");
Console.WriteLine(body);
```
```rust
#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
let result = reqwest::Client::new()
.get("https://api.veille.io/v1/vat")
.header("x-api-key", "YOUR_API_KEY")
.query(&[("vat", "FR12345678901")])
.send().await?.json::().await?;
println!("{:#?}", result);
Ok(())
}
```
### Read the company details [#read-the-company-details]
A valid number returns `is_valid: true`, the `company_name`, `company_address`, and `country_code`.
```python
if result.get("is_valid"):
print(f"✅ Valid VAT number")
print(f" Company : {result.get('company_name')}")
print(f" Address : {result.get('company_address')}")
print(f" Country : {result.get('country_code')}")
else:
print(f"❌ Invalid VAT number: {result.get('error', 'Not found in VIES')}")
```
```typescript
if (result.is_valid) {
console.log("✅ Valid VAT number");
console.log(` Company : ${result.company_name}`);
console.log(` Address : ${result.company_address}`);
console.log(` Country : ${result.country_code}`);
} else {
console.log(`❌ Invalid VAT number: ${result.error ?? "Not found in VIES"}`);
}
```
```php
if ($result["is_valid"] ?? false) {
echo "✅ Valid VAT number\n";
echo " Company : {$result['company_name']}\n";
echo " Address : {$result['company_address']}\n";
echo " Country : {$result['country_code']}\n";
} else {
echo "❌ Invalid VAT number: " . ($result["error"] ?? "Not found in VIES") . "\n";
}
```
```go
if result["is_valid"].(bool) {
fmt.Printf("✅ Valid VAT number\n Company : %v\n Address : %v\n Country : %v\n",
result["company_name"], result["company_address"], result["country_code"])
} else {
errMsg := "Not found in VIES"
if e, ok := result["error"].(string); ok { errMsg = e }
fmt.Println("❌ Invalid VAT number:", errMsg)
}
```
```java
import org.json.*;
var r = new JSONObject(response.body());
if (r.getBoolean("is_valid")) {
System.out.printf("✅ Valid VAT number%n Company : %s%n Address : %s%n Country : %s%n",
r.getString("company_name"), r.getString("company_address"), r.getString("country_code"));
} else {
System.out.println("❌ Invalid VAT number: " + r.optString("error", "Not found in VIES"));
}
```
```csharp
using System.Text.Json;
var r = JsonDocument.Parse(body).RootElement;
if (r.GetProperty("is_valid").GetBoolean())
{
Console.WriteLine("✅ Valid VAT number");
Console.WriteLine($" Company : {r.GetProperty("company_name")}");
Console.WriteLine($" Address : {r.GetProperty("company_address")}");
Console.WriteLine($" Country : {r.GetProperty("country_code")}");
}
else
{
var error = r.TryGetProperty("error", out var e) ? e.GetString() : "Not found in VIES";
Console.WriteLine($"❌ Invalid VAT number: {error}");
}
```
```rust
if result["is_valid"].as_bool().unwrap_or(false) {
println!("✅ Valid VAT number");
println!(" Company : {}", result["company_name"].as_str().unwrap_or(""));
println!(" Address : {}", result["company_address"].as_str().unwrap_or(""));
println!(" Country : {}", result["country_code"].as_str().unwrap_or(""));
} else {
let err = result["error"].as_str().unwrap_or("Not found in VIES");
println!("❌ Invalid VAT number: {}", err);
}
```
### Build a B2B checkout VAT handler [#build-a-b2b-checkout-vat-handler]
Strip VAT from the order total when a verified EU business VAT number is provided.
```python
import requests
API_KEY = "YOUR_API_KEY"
VAT_RATE = 0.20 # 20% VAT
def lookup_vat(number: str) -> dict:
r = requests.get("https://api.veille.io/v1/vat",
headers={"x-api-key": API_KEY}, params={"vat": number})
return r.json()
def calculate_checkout(subtotal: float, vat_number: str | None = None) -> dict:
vat_amount = subtotal * VAT_RATE
vat_info = None
if vat_number:
result = lookup_vat(vat_number)
if result.get("is_valid"):
vat_amount = 0 # B2B reverse charge — no VAT charged
vat_info = {"company": result["company_name"], "country": result["country_code"]}
else:
return {"error": "The VAT number you provided is not valid."}
total = subtotal + vat_amount
return {"subtotal": subtotal, "vat": vat_amount, "total": total, "company": vat_info}
print(calculate_checkout(100.00))
print(calculate_checkout(100.00, vat_number="FR12345678901"))
print(calculate_checkout(100.00, vat_number="INVALID123"))
```
```typescript
const API_KEY = "YOUR_API_KEY";
const VAT_RATE = 0.20;
async function lookupVat(number: string) {
const params = new URLSearchParams({ vat: number });
const res = await fetch(`https://api.veille.io/v1/vat?${params}`, {
headers: { "x-api-key": API_KEY },
});
return res.json();
}
async function calculateCheckout(subtotal: number, vatNumber?: string) {
let vatAmount = subtotal * VAT_RATE;
let companyInfo: any = null;
if (vatNumber) {
const result = await lookupVat(vatNumber);
if (result.is_valid) {
vatAmount = 0;
companyInfo = { company: result.company_name, country: result.country_code };
} else {
return { error: "The VAT number you provided is not valid." };
}
}
return { subtotal, vat: vatAmount, total: subtotal + vatAmount, company: companyInfo };
}
console.log(await calculateCheckout(100));
console.log(await calculateCheckout(100, "FR12345678901"));
console.log(await calculateCheckout(100, "INVALID123"));
```
```php
$number]);
$ch = curl_init("https://api.veille.io/v1/vat?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
return $result;
}
function calculateCheckout(string $apiKey, float $subtotal, ?string $vatNumber = null): array {
$vatAmount = $subtotal * VAT_RATE;
$company = null;
if ($vatNumber) {
$result = lookupVat($apiKey, $vatNumber);
if ($result["is_valid"] ?? false) {
$vatAmount = 0;
$company = ["company" => $result["company_name"], "country" => $result["country_code"]];
} else {
return ["error" => "Invalid VAT number."];
}
}
return ["subtotal" => $subtotal, "vat" => $vatAmount, "total" => $subtotal + $vatAmount, "company" => $company];
}
print_r(calculateCheckout("YOUR_API_KEY", 100.0));
print_r(calculateCheckout("YOUR_API_KEY", 100.0, "FR12345678901"));
```
```go
package main
import (
"encoding/json"
"fmt"
"io"
"net/http"
)
const APIKey = "YOUR_API_KEY"
const VATRate = 0.20
func lookupVAT(number string) map[string]any {
req, _ := http.NewRequest("GET", "https://api.veille.io/v1/vat?vat="+number, nil)
req.Header.Set("x-api-key", APIKey)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var r map[string]any
json.Unmarshal(body, &r)
return r
}
func calculateCheckout(subtotal float64, vatNumber string) map[string]any {
vatAmount := subtotal * VATRate
var company map[string]any
if vatNumber != "" {
result := lookupVAT(vatNumber)
if result["is_valid"].(bool) {
vatAmount = 0
company = map[string]any{"company": result["company_name"], "country": result["country_code"]}
} else {
return map[string]any{"error": "Invalid VAT number."}
}
}
return map[string]any{"subtotal": subtotal, "vat": vatAmount, "total": subtotal + vatAmount, "company": company}
}
func main() {
fmt.Println(calculateCheckout(100, ""))
fmt.Println(calculateCheckout(100, "FR12345678901"))
fmt.Println(calculateCheckout(100, "INVALID123"))
}
```
```java
import java.net.URI;
import java.net.http.*;
import org.json.*;
public class Main {
static HttpClient client = HttpClient.newHttpClient();
static String API_KEY = "YOUR_API_KEY";
static double VAT_RATE = 0.20;
static JSONObject lookupVat(String number) throws Exception {
var req = HttpRequest.newBuilder()
.uri(URI.create("https://api.veille.io/v1/vat?vat=" + number))
.header("x-api-key", API_KEY).GET().build();
var resp = client.send(req, HttpResponse.BodyHandlers.ofString());
return new JSONObject(resp.body());
}
static JSONObject calculateCheckout(double subtotal, String vatNumber) throws Exception {
double vatAmount = subtotal * VAT_RATE;
JSONObject company = null;
if (vatNumber != null && !vatNumber.isEmpty()) {
var result = lookupVat(vatNumber);
if (result.getBoolean("is_valid")) {
vatAmount = 0;
company = new JSONObject().put("company", result.getString("company_name"))
.put("country", result.getString("country_code"));
} else {
return new JSONObject().put("error", "Invalid VAT number.");
}
}
return new JSONObject().put("subtotal", subtotal).put("vat", vatAmount)
.put("total", subtotal + vatAmount).put("company", company);
}
public static void main(String[] args) throws Exception {
System.out.println(calculateCheckout(100, null));
System.out.println(calculateCheckout(100, "FR12345678901"));
System.out.println(calculateCheckout(100, "INVALID123"));
}
}
```
```csharp
using System.Net.Http;
using System.Text.Json;
const double VAT_RATE = 0.20;
var apiKey = "YOUR_API_KEY";
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", apiKey);
async Task LookupVat(string number)
{
var body = await client.GetStringAsync($"https://api.veille.io/v1/vat?vat={number}");
return JsonDocument.Parse(body).RootElement;
}
async Task CalculateCheckout(double subtotal, string? vatNumber = null)
{
double vatAmount = subtotal * VAT_RATE;
string? company = null;
if (vatNumber != null)
{
var result = await LookupVat(vatNumber);
if (result.GetProperty("is_valid").GetBoolean())
{ vatAmount = 0; company = result.GetProperty("company_name").GetString(); }
else return """{"error":"Invalid VAT number."}""";
}
return $"""{{ "subtotal": {subtotal}, "vat": {vatAmount}, "total": {subtotal + vatAmount}, "company": "{company}" }}""";
}
Console.WriteLine(await CalculateCheckout(100));
Console.WriteLine(await CalculateCheckout(100, "FR12345678901"));
Console.WriteLine(await CalculateCheckout(100, "INVALID123"));
```
```rust
use reqwest::Client;
use serde_json::{json, Value};
const VAT_RATE: f64 = 0.20;
const API_KEY: &str = "YOUR_API_KEY";
async fn lookup_vat(client: &Client, number: &str) -> Value {
client.get("https://api.veille.io/v1/vat")
.header("x-api-key", API_KEY)
.query(&[("vat", number)])
.send().await.unwrap().json::().await.unwrap()
}
async fn calculate_checkout(client: &Client, subtotal: f64, vat_number: Option<&str>) -> Value {
let mut vat_amount = subtotal * VAT_RATE;
let mut company = json!(null);
if let Some(number) = vat_number {
let result = lookup_vat(client, number).await;
if result["is_valid"].as_bool().unwrap_or(false) {
vat_amount = 0.0;
company = json!({"company": result["company_name"], "country": result["country_code"]});
} else {
return json!({ "error": "Invalid VAT number." });
}
}
json!({ "subtotal": subtotal, "vat": vat_amount, "total": subtotal + vat_amount, "company": company })
}
#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
let client = Client::new();
println!("{}", calculate_checkout(&client, 100.0, None).await);
println!("{}", calculate_checkout(&client, 100.0, Some("FR12345678901")).await);
println!("{}", calculate_checkout(&client, 100.0, Some("INVALID123")).await);
Ok(())
}
```
Always store the validated company name and address alongside the order record. EU tax authorities require proof that the reverse-charge mechanism was correctly applied.
# Profile and account settings (/account/profile-and-settings)
Two screens, two scopes: **Profile** holds what is personal to you and follows you across accounts, while **Account** holds settings that affect every member of the selected account.
## Which setting lives where [#which-setting-lives-where]
| Setting | Where |
| --------------------------------------------------------------- | -------------------------------------- |
| Your name, avatar, and interface language | **Settings → Profile** |
| Your password | **Settings → Profile → Security** |
| Product and usage update emails for you | **Settings → Profile → Notifications** |
| **Name**, **Company logo**, and country (currency is read-only) | **Settings → Account** |
| Weekly and monthly usage reports for the account | **Settings → Account** |
| Log privacy and account deletion | **Settings → Account** |
## Notifications [#notifications]
| Kind | Where it is controlled |
| ------------------------------------------ | -------------------------------------------------------------------- |
| Product updates and personal usage alerts | **Settings → Profile → Notifications** (follows you across accounts) |
| Weekly / monthly **account** usage reports | **Settings → Account → Notifications** (shared with every member) |
## Log privacy [#log-privacy]
Turning on log privacy stops the dashboard from storing the parameters sent with each request. Status codes, durations, and credit costs are still recorded, so billing and monitoring keep working — but you lose the request payload when debugging.
## Danger zone [#danger-zone]
* **Delete your user** from **Settings → Profile** removes only you. Account data stays for the remaining members.
* **Delete the account** from **Settings → Account** is irreversible: keys, logs, and credits for that account are gone. You must type the account slug to confirm.
Your sign-in email is read-only in the dashboard. Open a [support ticket](/help/support-tickets) from **Settings → Support** if you need it changed.
## Related [#related]
# Auto top-up (/billing/auto-top-up)
Auto top-up watches your remaining balance and buys a pack for you when it drops below a threshold you choose. It keeps production running when consumption spikes overnight.
### Open subscription settings [#open-subscription-settings]
Go to **Settings → Subscription** and find the **Auto top-up** section.
### Choose a pack and a threshold [#choose-a-pack-and-a-threshold]
Pick the **one-time pack** to buy automatically, then the percentage of remaining balance that triggers it — between 10% and 30%.
### Save [#save]
Enabling auto top-up does not charge you. The first charge only happens when your balance actually crosses the threshold.
## How the threshold is measured [#how-the-threshold-is-measured]
The percentage is calculated on your **combined** remaining balance (API quota plus extra credits), not on a single bucket. When that percentage drops to or below the threshold you set, the configured one-time pack is purchased automatically.
## Built-in protections [#built-in-protections]
| Protection | Effect |
| --------------------------- | --------------------------------------------------------------------------------- |
| **Threshold only** | A purchase fires on balance, never on a schedule or a fixed date. |
| **72-hour cooldown** | After a top-up, no other automatic purchase can fire for 72 hours. |
| **Auto-disable on failure** | If the payment fails, auto top-up switches off so you are not charged repeatedly. |
| **Paid plan required** | Free-trial workspaces cannot enable auto top-up — subscribe first. |
Auto top-up requires a paid plan and a valid payment method. If a charge fails, the feature is disabled and you have to re-enable it manually after updating your card.
## Related [#related]
# Credits and balances (/billing/credits)
Every billable call spends credits from your workspace. The dashboard **Usage** panel under **Settings → Subscription** shows three balances. The API usage endpoint reports a combined runway so you can alert from code without parsing every bucket.
## The three balances [#the-three-balances]
| Balance | What it is | Resets |
| ------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Subscription quota** | API calls included in your plan | Yes — at the start of each billing period (from Stripe when available, otherwise the calendar month). Unused quota does not roll over. |
| **One-time API pack** | Additional API quota from a one-time purchase | Never — consumed until depleted, across billing periods |
| **Pay-as-you-go credits** | A separate ledger used only after subscription quota and API packs are empty | Never — grants stay until spent |
In the dashboard those three bars appear under **Settings → Subscription → Usage** (and in the sidebar **API usage** panel). On the usage endpoint (`/v1/usage`), the `subscription` object is the **combined** API quota (subscription + remaining packs). Pay-as-you-go sits under `credits`. Top-level `remaining` is both added together.
## Consumption order [#consumption-order]
### Subscription quota first [#subscription-quota-first]
Billable calls fill the plan allowance for the current period.
### Then one-time API packs [#then-one-time-api-packs]
When the period allowance is used up, remaining pack quota is consumed next. Packs are attributed in purchase order.
### Then pay-as-you-go credits [#then-pay-as-you-go-credits]
Only if the combined API quota cannot cover the endpoint cost do we debit the pay-as-you-go ledger.
### Otherwise the call is refused [#otherwise-the-call-is-refused]
The API returns `402` with `Payment required`, and the request is not executed.
## What gets billed [#what-gets-billed]
| Outcome | Credits |
| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `200` or `201` (successful / accepted billable response) | Yes — the endpoint's credit cost |
| `404` | Usually yes — unless that endpoint marks 404 as free (shown in the Library and on the endpoint page) |
| `401`, `402`, `400`, `5xx`, and most other errors | No — and any pay-as-you-go hold is released |
| Per-row endpoints with **0** results | Free |
| Per-row endpoints with **N** results | N × the per-row cost — all or nothing (insufficient balance → `402` before any rows are returned) |
| `/v1/usage` and job status URLs | Always free — no quota check |
Each endpoint declares its cost in the **Library** (and in the **API reference**): **N credits per call** or **per row**. The balance is checked before the work starts, so a job is never accepted without the credits to pay for it. Polling a job status never costs credits.
## Buy more capacity [#buy-more-capacity]
### Open subscription settings [#open-subscription-settings]
Go to **Settings → Subscription** and click **View all plans** (or open [https://app.chartquery.com/pricing](https://app.chartquery.com/pricing)).
### Pick a one-time pack [#pick-a-one-time-pack]
Depending on the product, a pack adds to **API quota** (one-time API pack) or to the **pay-as-you-go** ledger. It never changes your subscription tier by itself. Larger packs usually cost less per credit.
### Confirm the payment [#confirm-the-payment]
Capacity is available as soon as payment succeeds, and an invoice is emailed to the billing address.
Purchased packs also appear under **Settings → Subscription → One-time packs**. To refill automatically when the combined balance drops, see [Auto top-up](/billing/auto-top-up).
## Where to read history [#where-to-read-history]
| Screen | What it shows |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Settings → Subscription → Usage** | Live remaining / used for the three balances in the current period |
| **API Logs** | Every request with status, duration, and credits charged — including subscription and pack usage |
| **Settings → Credits** | The **pay-as-you-go ledger only**: grants (rewards, some pack types, auto top-up) and spends that happened after API quota was empty. Filter by member or type. |
| **Usage endpoint** (`/v1/usage`) | Machine-readable snapshot: `remaining`, `subscription`, `credits`, `renewal_date` — free to call |
If **Settings → Credits** looks empty while Analytics shows traffic, that is expected: subscription and pack consumption never appear on that page. Use **API Logs** or the Usage bars instead.
## When you see `402` [#when-you-see-402]
| Message | Meaning | What to do |
| ----------------------------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------- |
| `Payment required` | No subscription quota, packs, or pay-as-you-go left for this call's cost | Buy a pack, upgrade the plan, or enable [auto top-up](/billing/auto-top-up) |
| `You have open invoices: …` | An unpaid invoice is blocking the account | Settle it under **Settings → Invoices** — balance alone is not enough |
| `Insufficient credits: X required, Y available` | A per-row endpoint would return more rows than you can afford | Top up, or narrow the request so fewer rows come back |
## FAQ [#faq]
* **Does unused plan quota roll over?** No. The subscription bucket resets each billing period.
* **Do one-time packs expire at month end?** No. They stay until consumed.
* **Do all keys share the same balances?** Yes — quota is workspace-wide.
* **Does checking usage cost credits?** No. `/v1/usage` and job status paths are free.
* **Why is dashboard Usage split but `/usage.subscription` combined?** So a single `remaining` number is enough for alerts; open the dashboard when you need the three-way split.
## Related [#related]
# Invoices and subscription (/billing/invoices-and-subscription)
Your plan sets your API quota for the period and your rate limits. Change it, update your payment details, and download past invoices from the billing pages.
## Change your plan [#change-your-plan]
Open **Settings → Subscription**, click **View all plans**, and pick another plan. Upgrades apply immediately with a prorated charge; downgrades take effect at the end of the current billing period, so you keep the quota you already paid for.
## Payment details and invoices [#payment-details-and-invoices]
* **Open billing portal** from **Settings → Invoices** or **Subscription** to change your card, company name, address, and VAT number. Set them before your first invoice so they appear on the document.
* Every invoice is listed under **Settings → Invoices** with its date, amount, and status, and can be downloaded as a **PDF**.
* Set the **billing email** on the same page to control where invoices are sent — use a finance alias rather than a personal address.
* An **upcoming invoice** may appear when a renewal is about to be charged — useful for forecasting the next bill.
## If an invoice stays unpaid [#if-an-invoice-stays-unpaid]
Open invoices block API traffic with `402`, even when credits remain. Settle them from the billing portal or the Invoices page, then retry. Do not keep retrying a `402` — it will fail again until the invoice is paid or the balance is topped up.
Cancelling stops the renewal but keeps your account and remaining credits. You can subscribe again later without losing your keys or history.
## Related [#related]
# Plans and pricing (/billing/plans-and-pricing)
These are the plans shown on the Chartquery dashboard pricing page ([https://app.chartquery.com/pricing](https://app.chartquery.com/pricing)). Your workspace picks one plan (or a one-time pack where available); the quota and rate limits on that plan apply to every API key in the workspace.
## Plans [#plans]
| Plan | Price | Quota |
| -------------- | ------- | ----------------------- |
| **Free trial** | $0/mo | 1,000 credits/month |
| **Starter** | $49/mo | 750,000 credits/month |
| **Pro** | $149/mo | 3,000,000 credits/month |
## How a plan applies [#how-a-plan-applies]
* Quota and rate limits are **workspace-wide**: every API key shares the same pool.
* Changing plan does not rotate or invalidate existing keys.
* One-time packs add to API quota without changing the subscription tier.
## Choose a plan [#choose-a-plan]
### Open billing settings [#open-billing-settings]
Go to **Settings → Subscription** and click **View all plans**, or open [https://app.chartquery.com/pricing](https://app.chartquery.com/pricing).
### Pick a plan or pack [#pick-a-plan-or-pack]
Subscription upgrades apply immediately with a prorated charge; downgrades take effect at the end of the current billing period. One-time packs add quota as soon as payment succeeds.
### Need a higher volume? [#need-a-higher-volume]
Pick a higher tier on the dashboard pricing page, or contact support if you need a custom volume.
Not sure which tier fits? Build a scenario in the [Simulator](/usage/simulator) first — it forecasts credits without sending traffic. Prices on this page match [https://app.chartquery.com/pricing](https://app.chartquery.com/pricing); checkout always shows the live amount before you confirm.
## Related [#related]
# Create your account (/getting-started/create-account)
Creating an account takes a minute and gives you a workspace, a starting credit balance, and access to the dashboard.
### Open the signup page [#open-the-signup-page]
Go to [https://app.chartquery.com/register](https://app.chartquery.com/register).
### Choose how to sign up [#choose-how-to-sign-up]
Use your email address and a password, or continue with **Google** or **GitHub** for a one-click signup.
### Verify your email [#verify-your-email]
We send a confirmation link to your inbox. Click it to activate the account. If it does not arrive within a few minutes, check your spam folder and request a new link from the sign-in page.
### Check your workspace name [#check-your-workspace-name]
Your account holds your API keys, credits, and invoices. Under **Settings → Account** you can set the **Name**, **Company logo**, and country. Currency is chosen at signup and is not editable afterwards.
## What you get next [#what-you-get-next]
* An account with a starting credit balance, so you can try the API before picking a plan.
* Access to the **Library**, **API Keys**, **API Logs**, and **Analytics**.
* A seat for yourself as **SuperUser** — invite teammates later under **Settings → Members**.
Use a shared team address (for example `dev@yourcompany.com`) for the first member. It keeps billing emails reachable when someone leaves.
## Related [#related]
# What is Chartquery? (/getting-started/overview)
Chartquery is an HTTP API you call from your own backend, automation platform, or AI agent. You send a request with your API key, we do the work, and you get structured JSON back. Each successful call consumes credits from your account balance.
## The three things you need [#the-three-things-you-need]
| What | Where |
| ---------- | ------------------------------------------------------------------------------------ |
| An account | Sign up on the dashboard at [https://app.chartquery.com](https://app.chartquery.com) |
| An API key | **API Keys** in the sidebar, sent as the `x-api-key` header |
| Credits | Included with your plan, topped up manually or automatically |
## What happens on a request [#what-happens-on-a-request]
### Your backend sends the call [#your-backend-sends-the-call]
The request hits `https://api.chartquery.com` with the `x-api-key` header. Never put the key in a browser or mobile app.
### We check the key and the balance [#we-check-the-key-and-the-balance]
Invalid, inactive, or expired keys return `401`. An empty balance or unpaid invoice returns `402`. Rate limits also return `401`, with a message that names the limit.
### We run the endpoint and return JSON [#we-run-the-endpoint-and-return-json]
On success you get structured data. The call is logged under **API Logs** with its status, duration, and credit cost.
### Credits are deducted only when the call succeeds [#credits-are-deducted-only-when-the-call-succeeds]
Successful responses are billed. Authentication failures, bad parameters, and server errors cost nothing — so you can experiment without burning the balance.
## What the dashboard is for [#what-the-dashboard-is-for]
The API itself is stateless: you authenticate with a key and get a response. The dashboard is where you manage everything around it — browsing the endpoint **Library**, issuing and revoking keys, watching consumption, downloading invoices, and inviting teammates. You never need the dashboard to make a call, but you will use it to keep an integration healthy.
After signup you land on the **Library**. The remaining balance also sits at the bottom of the sidebar on every screen, so you always know how much runway you have left.
## Related [#related]
# Quick start (/getting-started/quick-start)
This walkthrough takes you from an empty account to a successful API call. You will create a key, send a request, and confirm it in your logs.
### Create an account [#create-an-account]
Sign up at [https://app.chartquery.com/register](https://app.chartquery.com/register) and verify your email.
### Create an API key [#create-an-api-key]
Open **API Keys** in the sidebar and click **New API Key**. Give it a **Name** such as `local-dev` and pick the `development` category. The secret is shown **once** — copy it immediately.
### Store the key [#store-the-key]
Save the secret in an environment variable rather than in your source code:
```bash
export API_KEY="your-secret-key"
```
### Call the API [#call-the-api]
Send your first request with the key in the `x-api-key` header. The usage endpoint is free, so it is a safe way to verify that authentication works:
```bash
curl "https://api.chartquery.com/v1/usage" \
-H "x-api-key: $API_KEY"
```
### Confirm in the dashboard [#confirm-in-the-dashboard]
Open **API Logs** in the sidebar. Your call appears within a few seconds with its status code, duration, and credit cost.
## Prefer clicking first? [#prefer-clicking-first]
Open any endpoint in the **Library**, fill in the parameters in the **Playground**, and run it. That call uses the same credits and appears in the same logs — language tabs inside the playground (curl, Python, Node…) give you the equivalent snippet.
Never call the API directly from a browser or mobile app. Anyone can read the key from the network tab. Always proxy requests through your own backend.
## Related [#related]
# Sign in (/getting-started/sign-in)
Sign in at [https://app.chartquery.com](https://app.chartquery.com) with the method you used at signup. Email and social logins both lead to the same workspace as long as the address matches.
## Forgot your password [#forgot-your-password]
### Request a reset link [#request-a-reset-link]
Click **Forgot password** on the sign-in page and enter your email address.
### Open the email [#open-the-email]
The reset link is valid for a limited time. Request a new one if it has expired.
### Set a new password [#set-a-new-password]
Choose a new password and sign in. Existing API keys keep working: resetting a password never invalidates a key.
## Where you land [#where-you-land]
After a successful sign-in you open on the **Library** for your default workspace. If you belong to several workspaces, you may see the workspace picker first — pick one, then the same Library view appears.
## Switching workspaces [#switching-workspaces]
Use the switcher at the top of the sidebar to jump between workspaces. Credits, keys, and invoices are scoped per workspace, so make sure the right one is selected before creating a key or reading a balance.
Signed in with Google or GitHub? You have no password to reset. Use the same provider button, or set a password from **Settings → Profile → Security**.
## Related [#related]
# Finding your way around (/dashboard/navigation)
Everything in the dashboard hangs off the left sidebar. This page maps each entry to what you can do there, so you can stop hunting for a setting.
## The sidebar [#the-sidebar]
| Where | What you do there |
| ------------------------ | ---------------------------------------------------------------------------- |
| **Library** | Browse endpoints, read their parameters, and run them. |
| **Analytics** | Consumption per endpoint, per key, and over time. |
| **API Logs** | Per-request history with status, duration, and cost. |
| **API Keys** | Create, edit, deactivate, and rotate API keys. |
| **Settings → Account** | **Name**, **Company logo**, country (currency is read-only), and privacy. |
| **Settings → Members** | Invite teammates and manage their roles. |
| **Settings → Simulator** | Estimate the cost of a scenario before you build it. |
| **Settings → Billing** | **Subscription** (plan, auto top-up), **Invoices**, and **Credits** history. |
| **Settings → Support** | **New Ticket**, **My Tickets**, and **API Status**. |
## The API usage panel [#the-api-usage-panel]
At the foot of the sidebar, the **API usage** panel shows your remaining balances (subscription quota, one-time API pack, pay-as-you-go). **Upgrade** opens checkout for the current account. If an invoice is unpaid, a warning appears on the same panel. The combined runway is what the usage endpoint returns as `remaining`.
## The avatar menu [#the-avatar-menu]
Your avatar at the bottom of the sidebar opens, in order: **Profile**, **Subscription**, **Account**, the account audit **Logs** (who changed what — not the same as **API Logs**), **Affiliate**, **Feedback**, then theme and **Sign out**. Extra program links (**API Docs**, **Bug Bounty**, **Startup Program**, **Ambassador**) may also appear.
The account switcher sits at the top of the sidebar. If a key or invoice is missing, you are almost always looking at the wrong account.
## Related [#related]
# Dashboard overview (/dashboard/overview)
Signing in lands you on the **Library**, the catalogue of endpoints you can call. **Analytics** is the screen that tells you the state of your account: how many credits you are burning, how fast the API is answering, and whether recent calls are succeeding.
## What each Analytics panel tells you [#what-each-analytics-panel-tells-you]
| Panel | Read it when |
| ------------------------------------- | ------------------------------------------------------------------- |
| **Credits Usage** | You want to know how much of the period's quota you have consumed. |
| **Total Requests** | You need to compare traffic volume with your credit spend. |
| **Avg. Response Time** | Calls feel slow and you want to confirm it before raising a ticket. |
| **Endpoints Used** | You are checking that a migration actually switched endpoints. |
| **Status codes** and **Success Rate** | Failures may be wasting calls without producing results. |
## The Library [#the-library]
The Library lists every endpoint available on your plan with its credit cost. Open one to read its parameters, run it in the playground, or copy a ready-made code snippet.
## How the pieces fit together [#how-the-pieces-fit-together]
| You want to… | Go to |
| ------------------------------- | ------------------------------------------------ |
| Discover an endpoint and try it | **Library** → open the endpoint → playground |
| See if traffic is healthy today | **Analytics** (period filters at the top) |
| Debug one failed call | **API Logs** → filter → open the row |
| Know how much runway is left | **API usage** panel at the bottom of the sidebar |
| Buy more credits or change plan | **Settings → Subscription** |
Click **View more analytics** for the per-endpoint and per-key breakdown. Use **Customize** on Analytics to show, hide, or reorder the widgets.
## Related [#related]
# Common issues (/help/common-issues)
Most support tickets come down to a handful of causes. Work through this page first — it usually resolves the issue faster than waiting for a reply.
| Symptom | Most likely cause | Fix |
| ---------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Every call returns `401` | Wrong header name, or a space copied with the secret | The header is `x-api-key`. Re-copy the secret, or create a new key. |
| `401` `Rate limit exceeded` | A per-key quota, or your plan's rate limit | Spread the traffic out, raise the key's limits, or upgrade the plan. |
| Calls suddenly return `402` | Balance exhausted, or an unpaid invoice | Buy a [top-up](/billing/credits), enable [auto top-up](/billing/auto-top-up), or settle the invoice. |
| Timeouts at exactly 10s or 30s | Your platform aborts before we reply | Raise your function or client timeout to 60 seconds. |
| `400` on a request that used to work | A required parameter is missing or mistyped | Compare against the endpoint page in the **API reference**. |
| Credits drop faster than expected | Retries, or a loop calling the same endpoint | Check the [request logs](/usage/request-logs) for repeated identical calls. |
| Balance or keys missing in the dashboard | Wrong workspace selected | Use the switcher at the top of the sidebar. |
| Playground burns credits unexpectedly | Playground calls are real API calls | Use the free usage endpoint to test auth, or the [Simulator](/usage/simulator) to estimate cost without traffic. |
| `402` with credits still showing | An unpaid invoice is blocking the account | Open **Settings → Invoices**, settle the invoice, then retry. |
## A 60-second checklist [#a-60-second-checklist]
### Read the status code [#read-the-status-code]
`401` → key or rate limit. `402` → balance or invoice. `400` → parameters. `5xx` → retry with backoff.
### Find the row in API Logs [#find-the-row-in-api-logs]
Match the timestamp. Open the detail panel for the exact parameters and error message.
### Check the sidebar balance [#check-the-sidebar-balance]
If it is near zero, top up or enable auto top-up before retrying a production load.
## Still stuck [#still-stuck]
Open a [support ticket](/help/support-tickets) from **Settings → Support → New Ticket**. Include the endpoint, the timestamp, and the status code you saw — with those three, we can find the request in seconds. **API Status** on the same menu tells you whether the problem is on our side.
## Related [#related]
# Support tickets (/help/support-tickets)
When [common issues](/help/common-issues) does not unblock you, open a ticket from **Settings → Support**. You can attach logs, track replies, and mark the conversation resolved when you are done.
## Where to find it [#where-to-find-it]
In the dashboard sidebar, open **Settings → Support**. You get three entries: **New Ticket**, **My Tickets**, and **API Status**. Tickets are per workspace — switch account first if you have more than one.
## Open a ticket [#open-a-ticket]
### Choose New Ticket [#choose-new-ticket]
Go to **Settings → Support → New Ticket**. Read the **Support guidelines** banner before you submit.
### Fill in the form [#fill-in-the-form]
Add a short **Title**, set **Priority**, pick a **Category** and **Subcategory**, then describe the issue in the message. Attach a file if it helps.
### Submit [#submit]
Click **Create ticket**. You land on the ticket thread, and email notifications keep you updated when the team replies.
## What to include [#what-to-include]
* The **endpoint** path (for example `/v1/usage` or `/v2/google/search`).
* The **timestamp** of the failing call (UTC if you can).
* The **HTTP status code** and the exact `error` string from the response.
* A `request_id` from [API Logs](/usage/request-logs) when you have one.
* What you expected vs what you got, in one or two sentences.
Support is available **Monday to Friday, 9:00–17:00 (Paris time)**. We answer every ticket; response time depends on your plan and support level. Idle tickets may be closed by the team.
## Categories [#categories]
| Category | Typical subcategories |
| --------------- | ---------------------------------------------------------------- |
| **Billing** | Invoice, Payment failure, Refund or credit, Plan change |
| **Account** | API key, Dashboard login, Rate limit |
| **Technical** | API errors, Timeout / performance, Incorrect data, Endpoint down |
| **Integration** | SDK bug, Auth flow, Webhook |
| **Commercial** | Partnership, Reseller, Pricing, Custom plan, Review voucher |
## Priorities and statuses [#priorities-and-statuses]
| Field | Values |
| ------------ | --------------------------------------------- |
| **Priority** | Low, Medium, High, Urgent |
| **Status** | Open, In progress, Resolved, Closed, Archived |
## Follow the conversation [#follow-the-conversation]
Open any ticket from **My Tickets**. You see the original message, attachments, and the **Messages** thread. Reply with optional attachments while the ticket is open or in progress. When the issue is fixed on your side, click **Mark as resolved**. Replies are disabled once a ticket is **Resolved** or **Closed**.
* The Playground can pre-fill a technical ticket with endpoint and status context — complete the placeholders before you send.
* Check **API Status** on the same Support menu if you suspect a platform-wide incident.
## Limits [#limits]
* **Free trial** accounts can open **one** support ticket in total.
* **Paid** accounts can open up to **10 tickets per day**.
* Attachments accept `.png`, `.jpg`, `.jpeg`, `.txt`, `.log`, and `.json`, up to **10 MB**.
If you already have an active live chat, continue there — do not open a duplicate ticket for the same issue.
## Before you open a ticket [#before-you-open-a-ticket]
Work through [Common issues](/help/common-issues) first. Many `401`, `402`, and timeout cases are fixed from the dashboard without waiting for a reply.
## Related [#related]
# Create and manage API keys (/keys/create-and-manage)
API keys authenticate every request. You manage them under **API Keys** in the sidebar, where each key carries a name, a category, optional sliding-window limits, and an optional expiry date.
## Create a key [#create-a-key]
### Open the form [#open-the-form]
Go to **API Keys** and click **New API Key**.
### Fill in the details [#fill-in-the-details]
Give the key a **Name** you will recognise in logs (`prod-api`, `zapier`, `local-dev`), pick a **Category**, and optionally set an expiry date.
### Set request limits [#set-request-limits]
The **Request limits** tab caps how much a single key can spend. Leave the fields empty for an unlimited key.
### Copy the secret [#copy-the-secret]
The secret is displayed **once**, right after creation. Copy it into your secret manager or environment variables. If you lose it, create a new key — it cannot be recovered.
## Per-key limits [#per-key-limits]
| Limit | Counts |
| -------------------- | --------------------------------------- |
| **Global hard-stop** | Every request the key has ever made. |
| **Within 24h** | The last 24 hours, as a rolling window. |
| **Within 7d** | The last 7 days, as a rolling window. |
| **Within 30d** | The last 30 days, as a rolling window. |
The windows roll continuously rather than resetting at midnight or on the 1st. A key that hits its limit returns `401` with a message naming the quota, while the rest of your keys keep working.
## One key per environment [#one-key-per-environment]
| Environment | Category | Why |
| ----------------- | ------------- | ------------------------------------------- |
| Local development | `development` | Revoke freely without touching production. |
| CI and staging | `staging` | Isolate automated test traffic in the logs. |
| Production | `production` | Rotate on a schedule, watch it closely. |
## Deactivate, delete, or rotate [#deactivate-delete-or-rotate]
* **Deactivate** blocks the key immediately while keeping its history. Use it when a key may have leaked.
* **Delete** is only possible for keys that were never used. Anything with request history is kept for billing and auditing.
* **Rotate** by creating the replacement first, deploying it everywhere, then deactivating the old key. That order avoids downtime.
A leaked key can spend your entire balance. Deactivate it right away, then create a replacement — do not wait for the rotation window.
## Related [#related]
# Make your first call (/keys/first-call)
Once you have a key, authentication is a single header. This page shows the shape of a request, how to confirm it worked, and what to do when it does not.
## Send the request [#send-the-request]
Pass your key in the `x-api-key` header on every call. The usage endpoint is free, which makes it the safest way to verify a new key:
```bash
curl "https://api.chartquery.com/v1/usage" \
-H "x-api-key: $API_KEY"
```
```javascript
const res = await fetch("https://api.chartquery.com/v1/usage", {
headers: { "x-api-key": process.env.API_KEY },
})
if (!res.ok) throw new Error(`Request failed: ${res.status}`)
const usage = await res.json()
```
## What a successful usage response looks like [#what-a-successful-usage-response-looks-like]
A `200` from the usage endpoint means the key works. The JSON includes `remaining` (combined runway), `subscription` and `credits` balances, `renewal_date` when a period applies, and the `api_key` that made the call — including its quotas. None of that call costs credits.
## If it does not work [#if-it-does-not-work]
| Response | Cause | Fix |
| --------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `401 Invalid API Key` | The header is missing or the value is wrong | Check for a trailing space or newline in the copied secret |
| `401 Inactive API Key` | The key was deactivated | Reactivate it under **API Keys**, or create a new one |
| `401` `Rate limit exceeded` | A per-key quota or your plan's rate limit was hit | Slow down, or raise the limits on the key |
| `402` `Payment required` | No credits left, or an unpaid invoice | Add a [top-up](/billing/credits), enable [auto top-up](/billing/auto-top-up), or settle the invoice |
Set your HTTP client timeout to at least 60 seconds. Many platform defaults are far lower and abort the call before Chartquery has replied.
## Related [#related]
# Invite your team (/team/members-and-groups)
A workspace can hold several members, so keys, credits, and invoices are shared instead of tied to one personal account. Manage members under **Settings → Members**.
### Send an invitation [#send-an-invitation]
Go to **Settings → Members**, click **Invite member**, and enter your teammate's email address and name.
### Pick a role [#pick-a-role]
Roles control who can create keys, change the plan, and see invoices. Give billing access only to the people who need it.
### Follow the invitation [#follow-the-invitation]
Pending invitations stay listed on the same page until they are accepted, so you can chase or cancel them.
## Roles [#roles]
| Role | Typical use |
| ----------------- | ------------------------------------------------------- |
| **SuperUser** | Full control, including deleting the account. |
| **Admin** | Day-to-day administration: keys, members, and settings. |
| **Billing Admin** | Plan, invoices, and payment details. |
| **User** | Everyday usage without administrative changes. |
Not sure which one to pick? **View all roles and permissions** on the Members page shows the full matrix, permission by permission.
## Groups [#groups]
When **Groups** is enabled on your plan, the Members page also lets you organise people into groups for easier access management. If you do not see the tab, your plan does not include it yet.
## How invitations work [#how-invitations-work]
* The invitee receives an email with a link to `/invitation/...`. They can create an account or sign in if they already have one.
* Until they accept, the invitation stays under **Pending invitations** so you can resend or cancel it.
* Once accepted, they share the account's keys, credits, and invoices according to their role — they do not get a separate balance.
Removing a member does not revoke the API keys they created. Deactivate their keys under **API Keys** as part of offboarding.
## Related [#related]
# Monitor your usage (/usage/monitor-usage)
**Analytics** breaks down where your credits go. Use it to find the endpoint driving your bill, confirm a migration, or catch a client that started retrying in a loop.
## Filter first [#filter-first]
Pick a period (7, 30, or 90 days, or a custom range), then narrow by endpoint or by status code family. **View more analytics** opens the detailed screen, where you can also filter by API key and dig into recent logs without leaving Analytics.
## What to look at [#what-to-look-at]
| View | Answers |
| --------------------- | ----------------------------------------------------- |
| **Top endpoints** | Which calls cost the most credits? |
| **API key analytics** | Which environment or client is responsible? |
| **Traffic over time** | Is consumption stable, or did something change? |
| **Status codes** | Are failures wasting calls without producing results? |
## When numbers look wrong [#when-numbers-look-wrong]
* Confirm the **workspace** in the sidebar switcher — balances never mix across workspaces.
* Confirm the **period** filter. A quiet 7-day view can hide a spike from last month.
* Compare **credits usage** with **total requests**. If requests are high but credits are not, you may be hitting free endpoints or getting a lot of errors.
## Check your balance from code [#check-your-balance-from-code]
The usage endpoint returns the same numbers as the dashboard and is free to call. Query it on a schedule and alert your team before the balance runs out:
```bash
curl "https://api.chartquery.com/v1/usage" \
-H "x-api-key: $API_KEY"
```
Analytics is aggregated and can lag by a few minutes. For request-level accuracy, use the [request logs](/usage/request-logs).
## Related [#related]
# Request logs (/usage/request-logs)
Every call is recorded under **API Logs**, with the endpoint, status code, duration, caller IP, and credits charged. This is where you go when a request behaved unexpectedly.
## Debugging a failed call [#debugging-a-failed-call]
### Find the request [#find-the-request]
Filter by date range, API key, endpoint, status, or IP — or paste a request ID straight into the search box.
### Open the detail view [#open-the-detail-view]
Click the row to open a panel with the parameters that were sent and the response that was returned.
### Match it to a status code [#match-it-to-a-status-code]
`400` means a parameter is wrong, `401` points at the key or a rate limit, `402` means an empty balance, and `500` is on our side and worth retrying.
## Make the screen yours [#make-the-screen-yours]
* Toggle columns to show what matters to you: credits, speed, IP, parameters, or the error message.
* Switch to the **time series** view to see the same filtered traffic as a chart.
* Save a set of filters as a view so you can come back to it in one click.
* Turn on auto-refresh when you are watching a live incident.
## What is stored [#what-is-stored]
By default each row keeps the parameters that were sent and a truncated response body. If your workspace turns on **log privacy** under **Settings → Account**, parameters stop being stored — status, duration, and credit cost remain, so billing still works.
If your client reports a timeout but the log shows a `200`, the call succeeded and your own runtime closed the connection early. Raise your HTTP timeout to 60 seconds.
## Related [#related]
# Test endpoints and estimate cost (/usage/simulator)
The dashboard gives you two ways to try things before you commit: the **playground** on each Library endpoint sends real requests with your key attached, and the **Simulator** forecasts what a workload would cost without calling anything.
## Run a request in the playground [#run-a-request-in-the-playground]
### Open an endpoint [#open-an-endpoint]
Go to **Library** and open the endpoint you want to try.
### Fill in the parameters [#fill-in-the-parameters]
Required fields are marked. Optional ones fall back to their documented defaults.
### Run it and read the response [#run-it-and-read-the-response]
You get the status code and the response body on the **Response** tab. Language tabs inside the **Playground** (curl, Python, Node…) copy the same call as a snippet.
Playground calls are real API calls: they consume credits and appear in your logs exactly like production traffic.
## Estimate a workload with the Simulator [#estimate-a-workload-with-the-simulator]
**Settings → Simulator** answers the other question: what would this cost? Add the endpoints you plan to call, set a number of requests for each, and pick a plan. You get the total requests, the credits needed, and any excess beyond the plan — then you can email the estimate to yourself or to whoever signs off on it.
The Simulator sends no traffic and consumes no credits, so it is the safe way to size a plan before a launch.
## Related [#related]