Skip to content
Browsabledocs
↑ ↓ to navigate · Enter to openQuick links
Staging API reference · Requests use https://api-ingress-worker-staging.browsable-staging.workers.dev
Documentation Quickstart
Markdown ↗
Get started

Make your first request.

You need an API key and a few inputs. This example searches public Reddit posts; the same flow works for the rest of the catalogue.

1. Get an API key

Open your Browsable dashboard, choose API keys, and copy a key. Keep it in a server-side environment variable, not a public frontend.

2. Choose an API

Search the API reference by website or job. Each page lists its required inputs, limits and response format. You can also discover APIs programmatically with GET /v1/tasks?query=reddit.

3. Run a request

Replace YOUR_API_KEY with your key, then run this example. It submits a flat JSON body and polls the run until it finishes. The cURL example uses jq to read JSON.

RUN=$(curl -s -X POST "https://api-ingress-worker-staging.browsable-staging.workers.dev/v1/reddit/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"machine learning"}')

RUN_ID=$(echo "$RUN" | jq -er '.run_id // empty') || { echo "$RUN" >&2; exit 1; }
POLL_DELAY=3

while true; do
  RESULT=$(curl -s -H "Authorization: Bearer YOUR_API_KEY" "https://api-ingress-worker-staging.browsable-staging.workers.dev/v1/runs/$RUN_ID")
  STATUS=$(echo "$RESULT" | jq -r '.run_status')
  if [[ "$STATUS" =~ ^(succeeded|failed|errored|cancelled|canceled|expired)$ ]]; then
    echo "$RESULT"
    break
  fi
  sleep "$(awk "BEGIN { print $POLL_DELAY * (0.9 + ($RANDOM % 21) / 100) }")"
  POLL_DELAY=$((POLL_DELAY < 30 ? POLL_DELAY * 2 : 30))
  [ "$POLL_DELAY" -gt 30 ] && POLL_DELAY=30
done

4. Read the result

Wait for run_status: succeeded, then use result. A successful HTTP response can also describe a pending or failed run. On failure, inspect error before retrying.

JSON
{
  "run_id": "00000000-0000-4000-8000-000000000001",
  "task_key": "reddit-search",
  "task_name": "Reddit Search",
  "run_status": "succeeded",
  "status_url": "/v1/runs/00000000-0000-4000-8000-000000000001",
  "result": {
    "count": 2,
    "results": [
      {
        "id": "1k9x2ab",
        "title": "What are the best resources for learning machine learning in 2026?",
        "author": "ml_beginner_42",
        "subreddit": "MachineLearning",
        "score": 187,
        "upvoteRatio": 0.96,
        "numComments": 54,
        "created": 1773328800,
        "url": "https://www.reddit.com/r/MachineLearning/comments/1k9x2ab/what_are_the_best_resources_for_learning_machine/",
        "isVideo": false,
        "selftext": "I have a solid Python background and want to move into practical ML projects. Looking for courses, books, and hands-on resources.",
        "thumbnail": "https://styles.redditmedia.com/t5_2r3gv/styles/communityIcon_example.png"
      },
      {
        "id": "1k93yz7",
        "title": "Show HN: I built a small model to classify research paper abstracts by topic",
        "author": "latent_vector",
        "subreddit": "programming",
        "score": 92,
        "upvoteRatio": 0.91,
        "numComments": 18,
        "created": 1773242400,
        "url": "https://www.reddit.com/r/programming/comments/1k93yz7/show_hn_i_built_a_small_model_to_classify/",
        "isVideo": false,
        "selftext": "It uses a lightweight embedding model and a simple classifier. I wrote up the approach and linked the repo in the comments.",
        "thumbnail": "https://b.thumbs.redditmedia.com/example-thumbnail.png"
      }
    ]
  },
  "error": null
}

Illustrative response generated from the public contract. It is not a captured live search.

Choose how to wait

Requests start asynchronously by default. Send _run: {"async": false} to wait for results within the request’s available time. It may still return a pending run, so always check its status. Execution options →

Next steps