Conventions & gotchas

Authentication

Every request needs your API key in the X-API-Key header. The Python SDK reads it from the PROFOUND_API_KEY env var.

import os
from profound import Profound

client = Profound(api_key=os.environ["PROFOUND_API_KEY"])
categories = client.organizations.categories.list()

curl https://api.tryprofound.com/v1/org/categories \
  -H "X-API-Key: your_api_key_here"

Generate a key in the app under Settings → API Keys. Treat it like a password: it has full access to your org’s data, including write endpoints such as creating prompts and running agents.

Rate limit

600 requests per hour, per key. Anything above returns 429 Too Many Requests. Cache responses where you can and batch period-over-period or multi-asset queries instead of fanning out.

`end_date` is exclusive — add one day

end_date is parsed at the start of that day in Eastern Time, so it’s excluded from the response. To include all of May 10, send end_date="2026-05-11".

Window you want to display	What to send
`May 4 → May 10` (7 days, inclusive)	`start_date="2026-05-04", end_date="2026-05-11"`
`April 1 → April 30` (full month)	`start_date="2026-04-01", end_date="2026-05-01"`

The date_interval buckets ("hour" / "day" / "week" / "month" / "quarter" / "year" / "relative_week") are also computed in ET. Weeks start on Sunday.

Read column positions from `info.query`, not your request

Each row in the response packs its metrics and dimensions as arrays. The order of values in those arrays is the order listed in info.query.metrics and info.query.dimensions, which echo your request. Look positions up there instead of hardcoding them:

order   = res.info.query["metrics"]
i_score = order.index("visibility_score")
score   = res.data[0].metrics[i_score]

A response always looks like this:

{
  "info": {
    "total_rows": 12345,
    "query": {
      "metrics": ["visibility_score", "share_of_voice"],
      "dimensions": ["asset_name"]
    }
  },
  "data": [
    { "metrics": [0.42, 0.17], "dimensions": ["<your-asset>"] }
  ]
}

Period-over-period deltas are client-side

The API doesn’t return change vs the previous period. Run the same call twice (current window and a prior window of equal length) and subtract.

Don’t average daily rows to get a period score

A call with dimensions=["date"] returns one row per day. A call without date returns one row for the whole window. These are different numbers: the period score is traffic-weighted, an average of daily rows is not. Use the no-date call for headlines; use the with-date call for charts. Never derive one from the other.

Pagination

Default pagination.limit is 10,000. Max is 50,000. Use info.total_rows (returned on every response) to decide whether to paginate. Almost all queries fit in a single 50k page; only heavy dimensions=["url", ...] citation queries usually need a second page.

pagination={"limit": 50000, "offset": 0}

If you do need more, increment offset by limit until you’ve covered total_rows.

Filters

Every report endpoint accepts a filters array of {field, operator, value} objects:

{ "field": "asset_name", "operator": "is", "value": "<your-asset-name>" }

Operator	What it does
`is`	Exact match (scalar value)
`not_is`	Not equal
`in`	Match any value in an array
`not_in`	Match none of the values in an array
`contains`	Substring match (case-sensitive)
`not_contains`	Negated substring match (case-sensitive)
`contains_case_insensitive`	Substring match (case-insensitive)
`not_contains_case_insensitive`	Negated substring match (case-insensitive)
`matches`	Regex match

UUID filters (model_id, region_id, topic_id, tag_id, persona_id) accept only is, not_is, in, and not_in. The substring and regex operators apply to name-based fields such as asset_name, root_domain, and url. prompt_type (with values like "visibility") maps to the app’s Prompt Type filter. Send prompt_type=visibility on Citations queries to mirror the default UI scope. prompt_type is deprecated in favor of analysis_type (values visibility, sentiment, sentiment_v2, accuracy); both are accepted today.

Error responses

Status	Meaning	What to check
`422`	Validation error	The response body’s `detail` field.
`401`	API key missing or invalid	The `X-API-Key` header; whether the key has been revoked.
`403`	Key valid but no access	The `category_id` may belong to a different org.
`404`	Wrong path	Typo or wrong API version.
`429`	Rate limited	Back off; throttle to ≤600/hr.
`5xx`	Server error	Retry with exponential backoff.

Timezones

All bucketing happens in Eastern Time. A “last 7 days” range anchored to your local clock can land on a different ET day than you expect. Anchor scheduled jobs to ET:

from datetime import datetime
from zoneinfo import ZoneInfo

today_et = datetime.now(ZoneInfo("America/New_York")).date()

Overview

Setup

Metrics

Visibility

Citations

Conventions & gotchas

Authentication

Rate limit

`end_date` is exclusive — add one day

Read column positions from `info.query`, not your request

Period-over-period deltas are client-side

Don’t average daily rows to get a period score

Filters

Error responses

Timezones

​Authentication

​Rate limit

​end_date is exclusive — add one day

​Read column positions from info.query, not your request

​Period-over-period deltas are client-side

​Don’t average daily rows to get a period score

​Pagination

​Filters

​Error responses

​Timezones

Authentication

Rate limit

`end_date` is exclusive — add one day

Read column positions from `info.query`, not your request

Period-over-period deltas are client-side

Don’t average daily rows to get a period score

Pagination

Filters

Error responses

Timezones