# Reddit tools

Seven tools including bounded newest-feed monitoring implemented; live verification pending.

## Search Reddit posts

Tool: `reddit_search_posts`

One page of ranked Reddit posts, across Reddit or within a subreddit.

Endpoint: `POST /api/social/tools/reddit_search_posts`

Cost: 5 product credits per call/page. No fixed number of rows per page. Use dry_run for the selected options' quote.

### Input JSON schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "subreddit": {
      "type": "string",
      "pattern": "^(?:r\\/)?[A-Za-z0-9_]{1,21}$"
    },
    "time_range": {
      "default": "all",
      "type": "string",
      "enum": [
        "all",
        "day",
        "week",
        "month",
        "year"
      ]
    },
    "cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 16384
    },
    "dry_run": {
      "default": false,
      "type": "boolean"
    },
    "max_credits": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "sort": {
      "default": "relevance",
      "type": "string",
      "enum": [
        "relevance",
        "new",
        "top",
        "comment_count"
      ]
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}
```

## Search Reddit comments

Tool: `reddit_search_comments`

One page of matching comments. Time windows are filtered locally; comment_count sorting is unsupported.

Endpoint: `POST /api/social/tools/reddit_search_comments`

Cost: 5 product credits per call/page. No fixed number of rows per page. Use dry_run for the selected options' quote.

### Input JSON schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "subreddit": {
      "type": "string",
      "pattern": "^(?:r\\/)?[A-Za-z0-9_]{1,21}$"
    },
    "time_range": {
      "default": "all",
      "type": "string",
      "enum": [
        "all",
        "day",
        "week",
        "month",
        "year"
      ]
    },
    "cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 16384
    },
    "dry_run": {
      "default": false,
      "type": "boolean"
    },
    "max_credits": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "sort": {
      "default": "relevance",
      "type": "string",
      "enum": [
        "relevance",
        "new",
        "top"
      ]
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}
```

## Get a Reddit thread

Tool: `reddit_get_post`

Read a thread's full post body and available metadata, without fetching comments.

Endpoint: `POST /api/social/tools/reddit_get_post`

Cost: 5 product credits per call/page. No fixed number of rows per page. Use dry_run for the selected options' quote.

### Input JSON schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "maxLength": 2048,
      "format": "uri"
    },
    "dry_run": {
      "default": false,
      "type": "boolean"
    },
    "max_credits": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "url"
  ],
  "additionalProperties": false
}
```

## Get Reddit thread comments

Tool: `reddit_get_comments`

One bounded page of comments and included replies, flattened in reading order.

Endpoint: `POST /api/social/tools/reddit_get_comments`

Cost: 5 product credits per call/page. No fixed number of rows per page. Use dry_run for the selected options' quote.

### Input JSON schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "maxLength": 2048,
      "format": "uri"
    },
    "cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 16384
    },
    "dry_run": {
      "default": false,
      "type": "boolean"
    },
    "max_credits": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "url"
  ],
  "additionalProperties": false
}
```

## Find Reddit communities

Tool: `reddit_search_subreddits`

Group one page of matching posts by community, with counts within that sample.

Endpoint: `POST /api/social/tools/reddit_search_subreddits`

Cost: 5 product credits per call/page. No fixed number of rows per page. Use dry_run for the selected options' quote.

### Input JSON schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "time_range": {
      "default": "all",
      "type": "string",
      "enum": [
        "all",
        "day",
        "week",
        "month",
        "year"
      ]
    },
    "dry_run": {
      "default": false,
      "type": "boolean"
    },
    "max_credits": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}
```

## Get a Reddit community

Tool: `reddit_get_subreddit`

Read community rules and weekly activity. Names are case-sensitive at the supplier.

Endpoint: `POST /api/social/tools/reddit_get_subreddit`

Cost: 5 product credits per call/page. No fixed number of rows per page. Use dry_run for the selected options' quote.

### Input JSON schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "subreddit": {
      "type": "string",
      "pattern": "^(?:r\\/)?[A-Za-z0-9_]{1,21}$"
    },
    "dry_run": {
      "default": false,
      "type": "boolean"
    },
    "max_credits": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "subreddit"
  ],
  "additionalProperties": false
}
```

## Check new Reddit posts

Tool: `reddit_get_new_posts`

Walk public newest-first feeds in a fixed window. Up to ten communities and three pages each per call; charged per fetched page. Never cached.

Endpoint: `POST /api/social/tools/reddit_get_new_posts`

Cost: 5 product credits per fetched community page. Quote reserves subreddits × pages × 5; unused pages are refunded. Never cached. Use dry_run for the maximum quote.

### Input JSON schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "subreddits": {
      "minItems": 1,
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^(?:r\\/)?[A-Za-z0-9_]{1,21}$"
      }
    },
    "since": {
      "default": "24h",
      "type": "string",
      "minLength": 1,
      "maxLength": 40
    },
    "pages": {
      "default": 1,
      "type": "integer",
      "minimum": 1,
      "maximum": 3
    },
    "match": {
      "default": [],
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 100
      }
    },
    "cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 16384
    },
    "dry_run": {
      "default": false,
      "type": "boolean"
    },
    "max_credits": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "subreddits"
  ],
  "additionalProperties": false
}
```