Search discussions

Try in Playground

RSS keyword discovery with optional subreddit, ranking, time-window, and result bounds. Unknown scores and metrics remain null.

POST/v1/searchx-api-key

Headers

Get your API key

x-api-keystringrequiredheader

Your ScrapeAtlas customer key. Create one on /account/ and set SCRAPEATLAS_API_KEY.

Content-Typestringrequiredheader

Must be application/json.

Request body

querystringrequiredbody

Required. Search text, 1–200 characters.

min 1 chars · max 200 chars

Examplemeal planning

subredditsstring[]default: []body

Up to five subreddit names; defaults to an empty list.

default: [] · up to 5 items

Example["MealPrepSunday"]

sortenumdefault: "relevance"body

top, new, or relevance; defaults to relevance.

one of: top, new, relevance · default: "relevance"

Examplerelevance

timeWindowenumdefault: "month"body

day, week, month, or year; defaults to month.

one of: day, week, month, year · default: "month"

Examplemonth

maxPostsintegerdefault: 25body

1–50 posts; defaults to 25.

default: 25 · 1 – 50

Example10

Response fields

requestIdstring

Always included.

min 1 chars · max 128 chars

Always included.

accounting.pageLoadsinteger

Always included.

≥ 0

accounting.httpRequestsinteger

Always included.

≥ 0

accounting.proxyBytesinteger

Always included.

≥ 0

accounting.challengeCountinteger

Always included.

≥ 0

accounting.durationMsnumber

Always included.

≥ 0

accounting.proxySessionIdstring

Always included.

min 1 chars · max 128 chars

accounting.rssRequestsintegeroptional

Optional.

≥ 0

statusstring

Always included.

up to 50 items

posts.idstring

Always included.

min 1 chars · max 128 chars

posts.subredditstring

Always included.

posts.titlestring

Always included.

min 1 chars · max 1000 chars

posts.permalinkstring

Always included.

max 2048 chars · absolute HTTPS URL

posts.urlstring

Always included.

max 4096 chars · absolute HTTPS URL

posts.authorstringnullable

Always included.

posts.createdAtstring

Always included.

posts.scoreintegernullable

Always included.

posts.upvoteRationumbernullable

Always included.

posts.commentCountintegernullable

Always included.

posts.flairstringnullable

Always included.

posts.selftextstring

Always included.

max 4000 chars

posts.retrievalStatusenum

Always included.

one of: success, partial, challenged, failed

HTTP 200 returns the success variant. Check status: partial means usable data with warnings, and failed or challenged requests carry a failure object described in Errors & responses.

Error codes

HTTP	failure.code	Meaning
400	`invalid_request`	The request failed validation.
401	`invalid_request`	The internal service secret is invalid.
503	`upstream_error` `breaker_open`	Proxy unavailable or thread retrieval temporarily paused.
502	`upstream_error`	Retrieval failed.
504	`timeout`	The deadline expired; available results are retained.
200	`partial` `challenged`	Inspect status and failure even when HTTP succeeds.

Code example

curl -X POST "https://api.scrapeatlas.com/v1/search" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"meal planning","subreddits":["MealPrepSunday"],"sort":"relevance","timeWindow":"month","maxPosts":10}'

const response = await fetch(
  "https://api.scrapeatlas.com/v1/search",
  {
    method: "POST",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "query": "meal planning",
      "subreddits": [
        "MealPrepSunday"
      ],
      "sort": "relevance",
      "timeWindow": "month",
      "maxPosts": 10
    })
  }
);

const data = await response.json();
console.log(data.status, data);

type Result = {
  status: "success" | "partial" | "failed" | "challenged";
  requestId: string;
  [field: string]: unknown;
};

const response = await fetch(
  "https://api.scrapeatlas.com/v1/search",
  {
    method: "POST",
    headers: {
      "x-api-key": process.env.SCRAPEATLAS_API_KEY!,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "query": "meal planning",
      "subreddits": [
        "MealPrepSunday"
      ],
      "sort": "relevance",
      "timeWindow": "month",
      "maxPosts": 10
    })
  }
);

const data = (await response.json()) as Result;
if (data.status === "failed" || data.status === "challenged") {
  throw new Error(`Reddit request failed: ${data.requestId}`);
}
console.log(data);

import requests

response = requests.post(
    "https://api.scrapeatlas.com/v1/search",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "query": "meal planning",
        "subreddits": [
            "MealPrepSunday"
        ],
        "sort": "relevance",
        "timeWindow": "month",
        "maxPosts": 10
    },
    timeout=60,
)
data = response.json()
print(data["status"], data)

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"query":"meal planning","subreddits":["MealPrepSunday"],"sort":"relevance","timeWindow":"month","maxPosts":10}`)
	req, _ := http.NewRequest("POST", "https://api.scrapeatlas.com/v1/search", body)
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("x-api-key", "YOUR_API_KEY")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var data map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&data)
	fmt.Println(data["status"], data)
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        var client = HttpClient.newHttpClient();
        var request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.scrapeatlas.com/v1/search"))
            .POST(HttpRequest.BodyPublishers.ofString("{\"query\":\"meal planning\",\"subreddits\":[\"MealPrepSunday\"],\"sort\":\"relevance\",\"timeWindow\":\"month\",\"maxPosts\":10}"))
            .header("Content-Type", "application/json")
            .header("x-api-key", "YOUR_API_KEY")
            .build();
        var response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

Use your sa_live_… customer key at https://api.scrapeatlas.com.

Responses

Successful result. Shape generated from the runtime contract; values are placeholders.

{
  "requestId": "string",
  "accounting": {
    "pageLoads": 0,
    "httpRequests": 0,
    "proxyBytes": 0,
    "challengeCount": 0,
    "durationMs": 0,
    "proxySessionId": "string",
    "rssRequests": 0
  },
  "status": "success",
  "posts": [
    {
      "id": "string",
      "subreddit": "string",
      "title": "string",
      "permalink": "https://example.com/",
      "url": "https://example.com/",
      "author": "string",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "score": 0,
      "upvoteRatio": 0,
      "commentCount": 0,
      "flair": "string",
      "selftext": "string",
      "retrievalStatus": "success"
    }
  ]
}

The request failed validation.

{
  "requestId": "string",
  "accounting": {
    "pageLoads": 0,
    "httpRequests": 0,
    "proxyBytes": 0,
    "challengeCount": 0,
    "durationMs": 0,
    "proxySessionId": "string",
    "rssRequests": 0
  },
  "status": "partial",
  "posts": [
    {
      "id": "string",
      "subreddit": "string",
      "title": "string",
      "permalink": "https://example.com/",
      "url": "https://example.com/",
      "author": "string",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "score": 0,
      "upvoteRatio": 0,
      "commentCount": 0,
      "flair": "string",
      "selftext": "string",
      "retrievalStatus": "success"
    }
  ],
  "failure": {
    "code": "invalid_request",
    "message": "Invalid request: missing, duplicate, unsupported or malformed parameters."
  }
}