API reference

Research supported public content with Basic source views, Enriched analysis, and bounded content history.

Quickstart

Benchmark returns structured research views for supported public posts, publishing accounts, and links.

You send a target. A target is a URL, a handle, or a platform ID. If Benchmark has a current result, it returns it. Otherwise, you can request an update.

Get an API key

Sign in at benchmark.app. Open API keys in the sidebar and create a key. Each key belongs to one workspace.

Paid operations need a plan or purchased credits. See Pricing and credits.

Set your base URL and key

Replace YOUR_API_KEY with your key. Keys start with sk_.

export BENCHMARK_API_BASE_URL="https://api.benchmark.app"
export BENCHMARK_API_KEY="YOUR_API_KEY"

Read a stored result

Request a Basic source view. Every read is a POST with a target.

curl -sS "$BENCHMARK_API_BASE_URL/v1/profiles/basic" \
  -H "authorization: Bearer $BENCHMARK_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "target": { "reference": "https://www.youtube.com/@example_channel" } }'

If Benchmark has a current result, it returns it.

Request an updated result

A read can return 404 NOT_FOUND with canRequestData: true. That means Benchmark has no current result yet. Call the matching refresh route to request one:

curl -sS "$BENCHMARK_API_BASE_URL/v1/profiles/basic/refresh" \
  -H "authorization: Bearer $BENCHMARK_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "target": { "reference": "https://www.youtube.com/@example_channel" } }'

Check the research job

The API calls this job a collection. Check it until its status is complete or failed. Replace COLLECTION_ID with the id from the refresh response.
```
curl -sS "$BENCHMARK_API_BASE_URL/v1/collections/COLLECTION_ID" \
  -H "authorization: Bearer $BENCHMARK_API_KEY"
```

Errors

Every error has a fixed code, a safe message, and a requestId. If you get a 429, wait before you try again.

Status	Codes	Meaning
`400`	`INVALID_REQUEST`, `INVALID_IDENTIFIER`	The request or ID is not valid.
`401`	`UNAUTHORIZED`	A valid API key is required.
`402`	`INSUFFICIENT_CREDITS`	You need a plan or credits. See pricing and credits.
`402`	`USAGE_CAPPED`	You reached your monthly spending limit. See pricing and credits.
`403`	`FORBIDDEN`	The key cannot do this.
`404`	`NOT_FOUND`, `COLLECTION_NOT_FOUND`	The entity or collection was not found.
`409`	`COLLECTION_ALREADY_DELIVERED`, `CONFLICT`	The collection was delivered, or the request conflicts with its current state.
`429`	`RATE_LIMIT_EXCEEDED`	Too many requests were sent. Wait, then try again.
`500`	`INTERNAL_ERROR`	The request failed.
`503`	`SERVICE_UNAVAILABLE`	The service is not available. Try again later.