AI Agent Integration

There are three ways to wire ReddGrow into an AI agent. Choose based on your architecture:

Pattern	Best for
CLI mode	Shell-based pipelines, quick context injection
Direct API calls	Agents with tool use / function calling
MCP	Claude Desktop with persistent tool access

Async jobs

Every Reddit read endpoint is an async job. The call returns 202 Accepted immediately with a jobId, and you poll the jobs endpoint until the result is ready. Polling is free (0 credits). Reads are priced per Reddit page fetched: credits for the pages your limit can need are reserved when the job is created, and the pages the scraper did not need are refunded when it finishes.

Create the job:

curl -H "x-api-key: $REDDGROW_API_KEY" \
  "https://api.reddgrow.ai/v1/reddit/subreddits/typescript/posts?sort=new&limit=25"

{
  "jobId": "job_01HXYZ...",
  "status": "queued"
}

Poll the job until status is completed or failed:

curl -H "x-api-key: $REDDGROW_API_KEY" \
  "https://api.reddgrow.ai/v1/reddit/jobs/job_01HXYZ..."

{
  "jobId": "job_01HXYZ...",
  "status": "completed",
  "creditsCharged": 2,
  "result": { "posts": [ ... ] }
}

Status	Meaning
`queued`	The job is waiting for the scraper
`running`	The scraper is reading Reddit
`completed`	`result` holds exactly what the endpoint returns
`failed`	`error` holds `{ status, message }`

A failed job reports 403, 404 or 429 when Reddit itself gave that answer, and 503 when ReddGrow's scraper was unavailable. A 503 refunds the full reservation (creditsCharged is 0). On a Reddit 403, 404 or 429 you pay for the pages fetched (at least 1) and the rest is refunded. creditsCharged on the finished job is the final amount, and it is never more than the reservation shown in the X-Credits-Used header.

Jobs are scoped to your organization, and jobs and results are kept for 24 hours. Most jobs finish in under a minute, and it can take a few minutes when the scraper is busy, so poll every few seconds and allow several minutes before giving up.

The reddgrow CLI does this for you. reddgrow reddit ... commands wait for the job (polling every 3 seconds, giving up after 15 minutes) and print the result. To skip waiting, pass --no-wait to print the jobId, then fetch it later:

reddgrow reddit subreddits posts typescript --sort new --no-wait
# jobId: job_01HXYZ...

reddgrow reddit job job_01HXYZ...

Pattern 1: CLI mode

The CLI's --mode agent flag outputs raw JSON with no formatting. This makes it easy to pipe directly into an agent's context. The CLI waits for each job to finish before printing.

# Inject recent subreddit activity into a Claude prompt
CONTEXT=$(reddgrow reddit subreddits posts typescript --sort top --time week --mode agent)

claude -p "You are a Reddit posting assistant. Here are this week's top posts in r/typescript: $CONTEXT

Write a post title and body for sharing this article: https://example.com/ts-generics"

Chain multiple lookups into a single context block:

POSTS=$(reddgrow reddit subreddits posts typescript --sort top --time week --mode agent)
COMMENTS=$(reddgrow reddit subreddits comments typescript --limit 50 --mode agent)

CONTEXT=$(jq -n \
  --argjson posts "$POSTS" \
  --argjson comments "$COMMENTS" \
  '{posts: $posts, comments: $comments}')

echo "$CONTEXT" | your-agent-script

Pattern 2: Direct API calls in tool use

For agents that support tool use or function calling, call the ReddGrow API directly from within a tool handler. Because reads are async jobs, the handler creates the job and polls it until it finishes.

const headers = { "x-api-key": process.env.REDDGROW_API_KEY };

async function readReddit(url) {
  const { jobId } = await fetch(url, { headers }).then((r) => r.json());

  while (true) {
    await new Promise((r) => setTimeout(r, 3000));
    const job = await fetch(
      `https://api.reddgrow.ai/v1/reddit/jobs/${jobId}`,
      { headers }
    ).then((r) => r.json());

    if (job.status === "completed") return job.result;
    if (job.status === "failed") throw new Error(job.error.message);
  }
}

Claude tool_use example

Define a tool that fetches recent activity in a subreddit:

{
  "name": "get_subreddit_activity",
  "description": "Fetch the top posts and recent comments of a subreddit before posting",
  "input_schema": {
    "type": "object",
    "properties": {
      "subreddit": {
        "type": "string",
        "description": "Subreddit name without the r/ prefix"
      }
    },
    "required": ["subreddit"]
  }
}

Handle the tool call in your code:

async function handleToolCall(toolName, toolInput) {
  if (toolName === "get_subreddit_activity") {
    const { subreddit } = toolInput;
    const base = `https://api.reddgrow.ai/agent/subreddits/${subreddit}`;

    const [posts, comments] = await Promise.all([
      readReddit(`${base}/posts?sort=top&t=week`),
      readReddit(`${base}/comments?limit=50`),
    ]);

    return { posts, comments };
  }
}

OpenAI function calling example

Define the function in the tools array:

const tools = [
  {
    type: "function",
    function: {
      name: "search_reddit",
      description: "Search Reddit posts by exact phrase, newest first",
      parameters: {
        type: "object",
        properties: {
          query: {
            type: "string",
            description: "Search query",
          },
          limit: {
            type: "number",
            description: "Number of results, max 25",
          },
        },
        required: ["query"],
      },
    },
  },
];

// Handle the function call
async function callFunction(name, args) {
  if (name === "search_reddit") {
    const params = new URLSearchParams({
      q: args.query,
      limit: String(args.limit ?? 10),
    });

    // Reads are async jobs; readReddit creates the job and polls it
    return readReddit(`https://api.reddgrow.ai/agent/posts/search?${params}`);
  }
}

Pattern 3: MCP

If you use Claude Desktop, Cursor, VS Code, or Claude.ai, you can connect to the ReddGrow MCP server. This gives the AI client persistent access to all ReddGrow tools without any code.

See the ReddGrow MCP Server guide for setup instructions.

Choosing a pattern

Use CLI mode when you control the orchestration script and want the simplest setup
Use direct API calls when your agent framework supports tool use and you want the agent to decide when to query Reddit
Use MCP when you use Claude Desktop and want Reddit access available in every conversation without code