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](https://dashboard.browsable.app) , 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](/docs/api.md)  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.

```bash
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
```

```javascript
const runResponse = await fetch("https://api-ingress-worker-staging.browsable-staging.workers.dev/v1/reddit/search", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "query": "machine learning"
}),
});

const runPayload = await runResponse.json();
if (!runResponse.ok) throw new Error(JSON.stringify(runPayload));
const runId = runPayload.run_id;
if (!runId) throw new Error("Run ID not found in response");
let pollDelayMs = 3000;

while (true) {
  const resultResponse = await fetch("https://api-ingress-worker-staging.browsable-staging.workers.dev/v1/runs/" + runId, {
    headers: { Authorization: "Bearer YOUR_API_KEY" },
  });
  const result = await resultResponse.json().catch(() => ({}));
  if (resultResponse.status === 429 || [502, 503, 504].includes(resultResponse.status)) {
    const retryAfter = resultResponse.headers.get("retry-after");
    await new Promise((resolve) => setTimeout(resolve, retryAfter ? Number(retryAfter) * 1000 : pollDelayMs));
    continue;
  }
  if (!resultResponse.ok) throw new Error(`Status request failed: ${resultResponse.status}`);
  const status = result.run_status;
  if (["succeeded", "failed", "errored", "cancelled", "canceled", "expired"].includes(status)) {
    console.log(result);
    break;
  }
  await new Promise((resolve) => setTimeout(resolve, pollDelayMs * (0.9 + Math.random() * 0.2)));
  pollDelayMs = Math.min(pollDelayMs * 2, 30000);
}
```

```python
import random
import time
import requests

run_response = requests.post(
    "https://api-ingress-worker-staging.browsable-staging.workers.dev/v1/reddit/search",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
    "query": "machine learning"
},
)
run_payload = run_response.json()
if not run_response.ok:
    raise RuntimeError(run_payload)
run_id = run_payload.get("run_id")
if not run_id:
    raise ValueError("Run ID not found in response")
poll_delay = 3.0

while True:
    result_response = requests.get(
        "https://api-ingress-worker-staging.browsable-staging.workers.dev/v1/runs/" + run_id,
        headers={"Authorization": "Bearer YOUR_API_KEY"},
    )
    if result_response.status_code == 429 or result_response.status_code in (502, 503, 504):
        retry_after = result_response.headers.get("Retry-After")
        time.sleep(float(retry_after) if retry_after else poll_delay)
        continue
    result_response.raise_for_status()
    result = result_response.json()
    status = result.get("run_status")
    if status in ("succeeded", "failed", "errored", "cancelled", "canceled", "expired"):
        print(result)
        break
    time.sleep(poll_delay * random.uniform(0.9, 1.1))
    poll_delay = min(poll_delay * 2, 30.0)
```

## 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 →](/docs/api/tasks/execute.md) 

## Next steps

- [See every Reddit search input](/docs/api/endpoints/post-reddit-search.md)

- [Handle pagination and errors](/docs/api/request-guide.md)

- [Connect an agent through MCP](/docs/guides/agents.md)

---
Source: https://browsable-api-ux-staging.pages.dev/docs/guides/quickstart