Skip to content
Benchmark

Getting started

Benchmark returns public social data for a profile, a post, or a link.

You send a target. A target is a URL, a handle, or a platform ID. If Benchmark has the data, you get it right away. If it does not, you ask Benchmark to collect it.

  1. 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.

  2. Set your base URL and key

    Replace YOUR_API_KEY with your key. Keys start with sk_.

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

  3. Read stored data

    Ask for Basic profile data. Every read is a POST with a target.

    Terminal window
    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/@mkbhd" } }'

    If Benchmark has the data, you get it back right away.

  4. Ask for data that is missing

    A read can return 404 NOT_FOUND with canRequestData: true. That means Benchmark does not have the data yet, but it can collect it. Call the matching refresh route:

    Terminal window
    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/@mkbhd" } }'

  5. Poll the collection

    A refresh returns a collection. A collection is a job that you check until its status is complete or failed. Replace COLLECTION_ID with the id from the refresh response.

    Terminal window
    curl -sS "$BENCHMARK_API_BASE_URL/v1/collections/COLLECTION_ID" \
      -H "authorization: Bearer $BENCHMARK_API_KEY"

Next