# Who Am I
Source: https://monid.ai/docs/api/auth/whoami

Return the identity behind the current API key or OAuth access token.

```text theme={null}
GET /v1/auth/whoami
```

Return the authenticated user and (when present) workspace behind the current API key or OAuth access token. Useful to verify credentials.

## Headers

| Header          | Required | Description                              |
| --------------- | -------- | ---------------------------------------- |
| `Authorization` | Yes      | `Bearer <api-key>` or OAuth access token |

## Example Request

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.monid.ai/v1/auth/whoami" \
    -H "Authorization: Bearer monid_live_..."
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch("https://api.monid.ai/v1/auth/whoami", {
    headers: { Authorization: "Bearer monid_live_..." },
  });
  ```

  ```python Python theme={null}
  import requests

  res = requests.get(
      "https://api.monid.ai/v1/auth/whoami",
      headers={"Authorization": "Bearer monid_live_..."},
  )
  ```
</CodeGroup>

## 200 OK

| Field                   | Type                | Description                                              |
| ----------------------- | ------------------- | -------------------------------------------------------- |
| `user`                  | object              | The authenticated user                                   |
| `user.userId`           | string              | User identifier                                          |
| `user.username`         | string              | Username (may be empty)                                  |
| `user.email`            | string \| undefined | Primary email, when known                                |
| `user.metadata`         | object              | Free-form user metadata                                  |
| `user.createdAt`        | string              | Record creation time (ISO 8601)                          |
| `user.updatedAt`        | string              | Record last-update time (ISO 8601)                       |
| `workspace`             | object \| undefined | The caller's workspace — absent when the caller has none |
| `workspace.workspaceId` | string              | Workspace identifier                                     |
| `workspace.name`        | string              | Workspace display name (may be empty)                    |
| `workspace.slug`        | string              | Workspace slug (may be empty)                            |
| `workspace.metadata`    | object              | Free-form workspace metadata                             |
| `workspace.createdAt`   | string              | Record creation time (ISO 8601)                          |
| `workspace.updatedAt`   | string              | Record last-update time (ISO 8601)                       |

### Example Response

```json theme={null}
{
  "user": {
    "userId": "user_abc123",
    "username": "jane",
    "email": "jane@acme.com",
    "metadata": {},
    "createdAt": "2026-01-15T09:00:00.000Z",
    "updatedAt": "2026-03-01T12:00:00.000Z"
  },
  "workspace": {
    "workspaceId": "org_abc123",
    "name": "Acme, Inc.",
    "slug": "acme-inc",
    "metadata": {},
    "createdAt": "2026-01-15T09:00:00.000Z",
    "updatedAt": "2026-03-01T12:00:00.000Z"
  }
}
```


# List Workspaces
Source: https://monid.ai/docs/api/auth/workspaces

List the workspaces your API key or OAuth token has access to.

```text theme={null}
GET /v1/auth/workspaces
```

List the workspaces your API key or OAuth access token has access to. Use the returned workspace IDs to set the `x-workspace-id` header on subsequent requests.

## Headers

| Header          | Required | Description                              |
| --------------- | -------- | ---------------------------------------- |
| `Authorization` | Yes      | `Bearer <api-key>` or OAuth access token |

## Example Request

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.monid.ai/v1/auth/workspaces" \
    -H "Authorization: Bearer monid_live_..."
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch("https://api.monid.ai/v1/auth/workspaces", {
    headers: { Authorization: "Bearer monid_live_..." },
  });
  ```

  ```python Python theme={null}
  import requests

  res = requests.get(
      "https://api.monid.ai/v1/auth/workspaces",
      headers={"Authorization": "Bearer monid_live_..."},
  )
  ```
</CodeGroup>

## 200 OK

| Field                      | Type           | Description                                                 |
| -------------------------- | -------------- | ----------------------------------------------------------- |
| `workspaces`               | array          | Workspaces the caller belongs to                            |
| `workspaces[].workspaceId` | string         | Workspace identifier — pass as `x-workspace-id` when needed |
| `workspaces[].slug`        | string \| null | Workspace slug. `null` when the workspace has no slug       |

### Example Response

```json theme={null}
{
  "workspaces": [
    {
      "workspaceId": "org_abc123",
      "slug": "acme-inc"
    },
    {
      "workspaceId": "org_def456",
      "slug": null
    }
  ]
}
```

## Using a Workspace ID

With a Monid API key, the workspace is bound to the key — no header needed. When authenticating with an OAuth/JWT access token that doesn't carry an organization context, include the `x-workspace-id` header so Monid knows which workspace to operate against:

```bash theme={null}
curl -X POST https://api.monid.ai/v1/discover \
  -H "Authorization: Bearer <access-token>" \
  -H "x-workspace-id: org_abc123" \
  -H "Content-Type: application/json" \
  -d '{"query":"twitter posts"}'
```


# Discover
Source: https://monid.ai/docs/api/discover

Search for data endpoints using natural language.

Search for data endpoints using natural language. The API uses AI-powered routing to match your query to the best available endpoints.

## Request

```text theme={null}
POST /v1/discover
```

### Headers

| Header          | Required | Description        |
| --------------- | -------- | ------------------ |
| `Authorization` | Yes      | `Bearer <api-key>` |
| `Content-Type`  | Yes      | `application/json` |

### Body

| Field      | Type   | Required | Description                                                                                                                                                                                                       |
| ---------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query`    | string | Yes      | A short natural language search query (1-1000 characters)                                                                                                                                                         |
| `limit`    | number | No       | Maximum results to return (default 5, max 40)                                                                                                                                                                     |
| `minScore` | number | No       | Minimum relevance score. Results scoring below this are filtered out. Scores fall in `(0, 1)`, so useful values are in that range (default 0.2; the schema accepts up to 2, but values above 1 return no results) |

### Example Request

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.monid.ai/v1/discover \
    -H "Authorization: Bearer monid_live_..." \
    -H "Content-Type: application/json" \
    -d '{
      "query": "twitter posts about AI",
      "limit": 5
    }'
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch("https://api.monid.ai/v1/discover", {
    method: "POST",
    headers: {
      "Authorization": "Bearer monid_live_...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      query: "twitter posts about AI",
      limit: 5,
    }),
  });

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.monid.ai/v1/discover",
      headers={
          "Authorization": "Bearer monid_live_...",
          "Content-Type": "application/json",
      },
      json={
          "query": "twitter posts about AI",
          "limit": 5,
      },
  )

  data = response.json()
  ```
</CodeGroup>

## Response

### 200 OK

| Field                      | Type                | Description                                                                                                                                              |
| -------------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `results`                  | array               | Matching endpoints                                                                                                                                       |
| `results[].provider`       | string              | Provider slug                                                                                                                                            |
| `results[].providerName`   | string \| undefined | Provider display name (may be absent)                                                                                                                    |
| `results[].endpoint`       | string              | Endpoint path                                                                                                                                            |
| `results[].description`    | string              | Endpoint description                                                                                                                                     |
| `results[].score`          | number              | Final relevance score in `(0, 1)`, used for sorting                                                                                                      |
| `results[].tags`           | string\[]           | Endpoint tags                                                                                                                                            |
| `results[].scoreBreakdown` | object              | Per-signal breakdown of the score (`querierScore` plus one entry per signal)                                                                             |
| `results[].price`          | object              | Pricing information                                                                                                                                      |
| `results[].price.type`     | string              | Pricing model, e.g. `"PER_CALL"`, `"PER_RESULT"` (other types such as `"BY_PERIOD"`, `"PER_UNIT_MATRIX"`, `"METERED"` may appear with additional fields) |
| `results[].price.amount`   | object              | Price as `{ "value": number, "currency": "USD" }`                                                                                                        |
| `results[].hints`          | object \| undefined | Ready-to-use next-step commands (may be absent)                                                                                                          |
| `query`                    | string              | The original search query                                                                                                                                |
| `count`                    | number              | Number of results returned                                                                                                                               |

### Example Response

```json theme={null}
{
  "results": [
    {
      "provider": "apify",
      "providerName": "Apify",
      "endpoint": "/apidojo/tweet-scraper",
      "description": "Scrape tweets by search terms, hashtags, or user handles",
      "score": 0.87,
      "tags": ["twitter", "social-media"],
      "scoreBreakdown": { "querierScore": 0.82 },
      "price": {
        "type": "PER_CALL",
        "amount": {
          "value": 0.003,
          "currency": "USD"
        }
      }
    }
  ],
  "query": "twitter posts about AI",
  "count": 1
}
```

## Next Step

Use [`POST /v1/inspect`](/docs/api/inspect) to get full details for a discovered endpoint.


# Inspect
Source: https://monid.ai/docs/api/inspect

Get full details for a specific data endpoint.

Get full details for a specific data endpoint, including its input schema, pricing, and documentation.

## Request

```text theme={null}
POST /v1/inspect
```

### Headers

| Header          | Required | Description        |
| --------------- | -------- | ------------------ |
| `Authorization` | Yes      | `Bearer <api-key>` |
| `Content-Type`  | Yes      | `application/json` |

### Body

| Field      | Type   | Required | Description                                      |
| ---------- | ------ | -------- | ------------------------------------------------ |
| `provider` | string | Yes      | Provider slug (e.g., `"apify"`)                  |
| `endpoint` | string | Yes      | Endpoint path (e.g., `"/apidojo/tweet-scraper"`) |

### Example Request

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.monid.ai/v1/inspect \
    -H "Authorization: Bearer monid_live_..." \
    -H "Content-Type: application/json" \
    -d '{
      "provider": "apify",
      "endpoint": "/apidojo/tweet-scraper"
    }'
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch("https://api.monid.ai/v1/inspect", {
    method: "POST",
    headers: {
      "Authorization": "Bearer monid_live_...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      provider: "apify",
      endpoint: "/apidojo/tweet-scraper",
    }),
  });

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.monid.ai/v1/inspect",
      headers={
          "Authorization": "Bearer monid_live_...",
          "Content-Type": "application/json",
      },
      json={
          "provider": "apify",
          "endpoint": "/apidojo/tweet-scraper",
      },
  )

  data = response.json()
  ```
</CodeGroup>

## Response

### 200 OK

| Field               | Type                   | Description                                                                                                                                              |
| ------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                | string                 | Unique inspection identifier                                                                                                                             |
| `provider`          | string                 | Provider slug                                                                                                                                            |
| `providerName`      | string \| undefined    | Provider display name (may be absent)                                                                                                                    |
| `endpoint`          | string                 | Endpoint path                                                                                                                                            |
| `method`            | string \| undefined    | HTTP method for this endpoint                                                                                                                            |
| `description`       | string                 | What the endpoint does                                                                                                                                   |
| `summary`           | string \| undefined    | Detailed overview                                                                                                                                        |
| `input`             | object \| undefined    | Structured input — a JSON Schema per parameter location                                                                                                  |
| `input.pathParams`  | object \| undefined    | JSON Schema for URL path parameters                                                                                                                      |
| `input.queryParams` | object \| undefined    | JSON Schema for query string parameters                                                                                                                  |
| `input.body`        | object \| undefined    | JSON Schema for the request body                                                                                                                         |
| `input.bodyType`    | string \| undefined    | Body content type: `"json"`, `"form"`, or `"multipart"`                                                                                                  |
| `price`             | object \| undefined    | Pricing information                                                                                                                                      |
| `price.type`        | string                 | Pricing model, e.g. `"PER_CALL"`, `"PER_RESULT"` (other types such as `"BY_PERIOD"`, `"PER_UNIT_MATRIX"`, `"METERED"` may appear with additional fields) |
| `price.amount`      | object                 | Price as `{ "value": number, "currency": "USD" }`                                                                                                        |
| `price.flatFee`     | object \| undefined    | Base fee per call as `{ "value": number, "currency": "USD" }` (PER\_RESULT only)                                                                         |
| `price.notes`       | string\[] \| undefined | Pricing notes                                                                                                                                            |
| `docUrl`            | string \| undefined    | Link to provider documentation                                                                                                                           |
| `notes`             | string\[] \| undefined | Operator-curated notes — quirks, pitfalls, best practices                                                                                                |
| `tags`              | string\[]              | Endpoint tags (e.g. `["verified"]`)                                                                                                                      |
| `hints`             | object \| undefined    | Ready-to-use next-step commands, keyed by a descriptive phrase                                                                                           |

### Example Response

```json theme={null}
{
  "id": "01HXYZ...",
  "provider": "apify",
  "providerName": "Apify",
  "endpoint": "/apidojo/tweet-scraper",
  "method": "POST",
  "description": "Scrape tweets by search terms, hashtags, or user handles",
  "summary": "A powerful Twitter scraping tool that allows you to extract tweets based on search queries.",
  "input": {
    "body": {
      "type": "object",
      "properties": {
        "searchTerms": {
          "type": "array",
          "items": { "type": "string" },
          "description": "List of search terms to query"
        },
        "maxItems": {
          "type": "number",
          "description": "Maximum number of items to return per search term"
        }
      }
    },
    "bodyType": "json"
  },
  "price": {
    "type": "PER_CALL",
    "amount": {
      "value": 0.003,
      "currency": "USD"
    }
  },
  "docUrl": "https://apify.com/apidojo/tweet-scraper",
  "tags": ["verified"],
  "hints": {
    "run this endpoint": "curl -X POST https://api.monid.ai/v1/run -H 'Authorization: Bearer <API_KEY>' -H 'Content-Type: application/json' -d '{\"provider\":\"apify\",\"endpoint\":\"/apidojo/tweet-scraper\",\"input\":{...}}'"
  }
}
```

## Next Step

Use [`POST /v1/run`](/docs/api/run) to execute the endpoint with your input.


# API Overview
Source: https://monid.ai/docs/api/overview

Discover, inspect, and run data endpoints programmatically.

The Monid HTTP API lets you discover, inspect, and run data endpoints programmatically.

## Base URL

```text theme={null}
https://api.monid.ai
```

## Authentication

All `/v1/*` endpoints require Bearer authentication — a Monid API key or an OAuth/JWT access token:

```text theme={null}
Authorization: Bearer monid_live_...
```

Create an API key at [https://app.monid.ai/access/api-keys](https://app.monid.ai/access/api-keys).

## Workspace Header

When you authenticate with a Monid API key, the workspace is bound to the key — no `x-workspace-id` header is needed. The header only applies when authenticating with an OAuth/JWT access token that does not carry an organization context; in that case pass it explicitly. Get the list of workspaces the caller can access with [`GET /v1/auth/workspaces`](/docs/api/auth/workspaces).

```text theme={null}
x-workspace-id: org_abc123
```

## Endpoints

### Auth

| Method | Path                                               | Description                                        |
| ------ | -------------------------------------------------- | -------------------------------------------------- |
| `GET`  | [`/v1/auth/whoami`](/docs/api/auth/whoami)         | Return the identity behind the current credentials |
| `GET`  | [`/v1/auth/workspaces`](/docs/api/auth/workspaces) | List workspaces the caller can access              |

### Endpoints

| Method | Path                                 | Description               |
| ------ | ------------------------------------ | ------------------------- |
| `POST` | [`/v1/discover`](/docs/api/discover) | Search for data endpoints |
| `POST` | [`/v1/inspect`](/docs/api/inspect)   | Get full endpoint details |
| `POST` | [`/v1/run`](/docs/api/run)           | Execute a data endpoint   |

### Runs

| Method | Path                                          | Description                  |
| ------ | --------------------------------------------- | ---------------------------- |
| `GET`  | [`/v1/runs`](/docs/api/runs/list)             | List runs                    |
| `GET`  | [`/v1/runs/:runId`](/docs/api/runs/get)       | Get run status and results   |
| `POST` | [`/v1/runs/:runId/stop`](/docs/api/runs/stop) | Stop a queued or running run |

### Wallet

| Method | Path                                                   | Description              |
| ------ | ------------------------------------------------------ | ------------------------ |
| `GET`  | [`/v1/wallet/balance`](/docs/api/wallet/balance)       | Get current balance      |
| `GET`  | [`/v1/wallet/activities`](/docs/api/wallet/activities) | List wallet transactions |

## Request Format

All request bodies must be JSON with `Content-Type: application/json`.

```bash theme={null}
curl -X POST https://api.monid.ai/v1/discover \
  -H "Authorization: Bearer monid_live_..." \
  -H "Content-Type: application/json" \
  -d '{"query": "twitter posts"}'
```

## Response Format

All responses return JSON. Successful responses return the resource directly. Error responses return:

```json theme={null}
{
  "code": 400,
  "message": "Descriptive error message"
}
```

## Pagination

All list endpoints use cursor-based pagination:

**Request:**

| Parameter | Type   | Default | Description                                                |
| --------- | ------ | ------- | ---------------------------------------------------------- |
| `limit`   | number | varies  | Maximum items to return (default and max vary by endpoint) |
| `cursor`  | string | —       | Opaque cursor from a previous response                     |

**Response:**

```json theme={null}
{
  "items": [],
  "cursor": "eyJsYXN0..."
}
```

If `cursor` is `null` or absent, you've reached the last page.

## Error Codes

| Code  | Meaning                                                                                                    |
| ----- | ---------------------------------------------------------------------------------------------------------- |
| `202` | Accepted — the operation runs asynchronously (async runs, stop requests)                                   |
| `400` | Bad request — invalid input, malformed JSON, or validation error                                           |
| `401` | Unauthorized — missing or invalid API key                                                                  |
| `402` | Payment required — insufficient wallet balance                                                             |
| `403` | Forbidden — key is valid but not associated with a workspace, or the resource belongs to another workspace |
| `404` | Not found — resource doesn't exist                                                                         |
| `408` | Request timeout — a synchronous run timed out (`TIMED_OUT`)                                                |
| `409` | Conflict — e.g. stopping a run that is terminal or not stoppable                                           |
| `500` | Internal server error                                                                                      |
| `502` | Bad gateway — the upstream provider rejected the call (e.g. provider-side payment error)                   |
| `503` | Service unavailable — e.g. the wallet is not active                                                        |

## Request Tracing

Every request is assigned a unique request ID via the `x-request-id` header. Include this ID when reporting issues.


# Run
Source: https://monid.ai/docs/api/run

Execute a data endpoint.

Execute a data endpoint.

For providers which are executed synchronously (e.g. People Data Labs), they return the results immediately; for others (e.g. Apify), the server will return 202 with a run ID and processes the request in the background.

## Request

```text theme={null}
POST /v1/run
```

### Headers

| Header          | Required | Description        |
| --------------- | -------- | ------------------ |
| `Authorization` | Yes      | `Bearer <api-key>` |
| `Content-Type`  | Yes      | `application/json` |

### Body

| Field      | Type   | Required | Description                                                              |
| ---------- | ------ | -------- | ------------------------------------------------------------------------ |
| `provider` | string | Yes      | Provider slug (e.g., `"apify"`)                                          |
| `endpoint` | string | Yes      | Endpoint path (e.g., `"/apidojo/tweet-scraper"`)                         |
| `input`    | object | No       | Input parameters matching the endpoint's input schema (defaults to `{}`) |

### Example Request

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.monid.ai/v1/run \
    -H "Authorization: Bearer monid_live_..." \
    -H "Content-Type: application/json" \
    -d '{
      "provider": "apify",
      "endpoint": "/apidojo/tweet-scraper",
      "input": {
        "searchTerms": ["AI"],
        "maxItems": 10
      }
    }'
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch("https://api.monid.ai/v1/run", {
    method: "POST",
    headers: {
      "Authorization": "Bearer monid_live_...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      provider: "apify",
      endpoint: "/apidojo/tweet-scraper",
      input: {
        searchTerms: ["AI"],
        maxItems: 10,
      },
    }),
  });

  const data = await response.json();

  if (response.status === 202) {
    // Async provider — poll for results
    const runId = data.runId;
    let result;
    while (true) {
      const poll = await fetch(`https://api.monid.ai/v1/runs/${runId}`, {
        headers: { "Authorization": "Bearer monid_live_..." },
      });
      result = await poll.json();
      if (["COMPLETED", "FAILED", "BLOCKED", "STOPPED", "TIMED_OUT"].includes(result.status)) break;
      await new Promise((resolve) => setTimeout(resolve, 5000));
    }
    console.log(result.output);
  } else {
    // Sync provider (e.g. PDL) — run completed immediately.
    // The HTTP status mirrors the provider's status (200, 404, 429, ...).
    console.log(data.output);
  }
  ```

  ```python Python theme={null}
  import requests
  import time

  response = requests.post(
      "https://api.monid.ai/v1/run",
      headers={
          "Authorization": "Bearer monid_live_...",
          "Content-Type": "application/json",
      },
      json={
          "provider": "apify",
          "endpoint": "/apidojo/tweet-scraper",
          "input": {
              "searchTerms": ["AI"],
              "maxItems": 10,
          },
      },
  )

  data = response.json()

  if response.status_code == 202:
      # Async provider — poll for results
      run_id = data["runId"]
      while True:
          result = requests.get(
              f"https://api.monid.ai/v1/runs/{run_id}",
              headers={"Authorization": "Bearer monid_live_..."},
          ).json()
          if result["status"] in ("COMPLETED", "FAILED", "BLOCKED", "STOPPED", "TIMED_OUT"):
              break
          time.sleep(5)
  else:
      # Sync provider — run completed immediately.
      # The HTTP status mirrors the provider's status (200, 404, 429, ...).
      result = data

  if result["status"] == "FAILED":
      print("Infrastructure error")
  elif result["status"] in ("BLOCKED", "STOPPED", "TIMED_OUT"):
      print(f"Run {result['status'].lower()}: {result.get('reason', 'no output returned')}")
  elif result.get("providerResponse", {}).get("httpStatus", 200) >= 400:
      print(f"Provider error: HTTP {result['providerResponse']['httpStatus']}")
  else:
      print(f"Success: {result.get('output')}")
  ```
</CodeGroup>

## Response

The response depends on the provider's execution mode:

* **Sync providers** return the completed result immediately — no polling needed. The HTTP status **mirrors the provider's HTTP status**: `200` on success, `404`/`429`/`500` etc. when the provider returned that status (a provider-side `402` is surfaced as `502`). A synchronous run that times out returns `408` (`TIMED_OUT`).
* **Async providers** return `202` with a run ID. Poll [`GET /v1/runs/:runId`](/docs/api/runs/get) for results.
* A run rejected by a control gate returns `200` with `status: "BLOCKED"` plus `reason` and `controls` fields.

### Completed (Sync)

The run completed immediately. Results are included in the response, and the HTTP status mirrors the provider's status.

| Field                         | Type                | Description                                                             |
| ----------------------------- | ------------------- | ----------------------------------------------------------------------- |
| `runId`                       | string              | Unique run identifier (ULID)                                            |
| `provider`                    | string              | Provider slug                                                           |
| `endpoint`                    | string              | Endpoint path                                                           |
| `status`                      | string              | Run status: `"COMPLETED"`                                               |
| `output`                      | any \| null         | Provider output data                                                    |
| `providerResponse`            | object              | Provider response metadata                                              |
| `providerResponse.httpStatus` | number              | Provider HTTP status code                                               |
| `providerResponse.error`      | object \| undefined | Provider error body (non-2xx)                                           |
| `price`                       | object              | Endpoint pricing (`amount` is `{ "value": number, "currency": "USD" }`) |
| `billing`                     | object \| undefined | Billing breakdown (absent until settled)                                |
| `billedUnits`                 | number              | Units of the price's billing unit consumed (`0` when nothing billable)  |
| `resultCount`                 | number              | Deprecated alias of `billedUnits`                                       |
| `resources`                   | array \| undefined  | Resources provisioned by this run, if any                               |
| `hints`                       | object \| undefined | Ready-to-use next-step commands                                         |
| `createdAt`                   | string              | ISO 8601 timestamp                                                      |
| `completedAt`                 | string              | ISO 8601 timestamp                                                      |

#### Example: Sync Success

```json theme={null}
{
  "runId": "01HXYZ1234567890ABCDEF",
  "provider": "pdl",
  "endpoint": "/person/enrich",
  "status": "COMPLETED",
  "output": {
    "full_name": "John Doe",
    "linkedin_url": "linkedin.com/in/johndoe"
  },
  "providerResponse": {
    "httpStatus": 200
  },
  "price": {
    "type": "PER_CALL",
    "amount": { "value": 0.003, "currency": "USD" }
  },
  "billing": {
    "calculatedCost": { "value": 3000, "unit": "MICRO_DOLLAR", "currency": "USD" },
    "actualCost": { "value": 0, "unit": "MICRO_DOLLAR", "currency": "USD" },
    "reportedCost": { "value": 3000, "unit": "MICRO_DOLLAR", "currency": "USD" }
  },
  "billedUnits": 1,
  "resultCount": 1,
  "createdAt": "2026-03-28T10:30:00.000Z",
  "completedAt": "2026-03-28T10:30:01.000Z"
}
```

#### Example: Sync Provider Error

The run completed, but the provider returned an error. Note `status` is still `"COMPLETED"` — the run lifecycle finished. The response's HTTP status mirrors the provider's status (here: `404 Not Found`).

```json theme={null}
{
  "runId": "01HXYZ1234567890ABCDEF",
  "provider": "pdl",
  "endpoint": "/person/enrich",
  "status": "COMPLETED",
  "output": null,
  "providerResponse": {
    "httpStatus": 404,
    "error": {
      "status": 404,
      "message": "No match found for the given query"
    }
  },
  "price": {
    "type": "PER_CALL",
    "amount": { "value": 0.003, "currency": "USD" }
  },
  "billing": {
    "calculatedCost": { "value": 3000, "unit": "MICRO_DOLLAR", "currency": "USD" },
    "actualCost": { "value": 0, "unit": "MICRO_DOLLAR", "currency": "USD" },
    "reportedCost": { "value": 0, "unit": "MICRO_DOLLAR", "currency": "USD" }
  },
  "billedUnits": 0,
  "resultCount": 0,
  "createdAt": "2026-03-28T10:30:00.000Z",
  "completedAt": "2026-03-28T10:30:01.000Z"
}
```

### 202 Accepted (Async)

The run has been created. Poll [`GET /v1/runs/:runId`](/docs/api/runs/get) for results.

| Field       | Type   | Description                                        |
| ----------- | ------ | -------------------------------------------------- |
| `runId`     | string | Unique run identifier (ULID)                       |
| `provider`  | string | Provider slug                                      |
| `endpoint`  | string | Endpoint path                                      |
| `status`    | string | `"READY"` — the run is queued and about to execute |
| `price`     | object | Endpoint pricing                                   |
| `createdAt` | string | ISO 8601 timestamp                                 |

#### Example

```json theme={null}
{
  "runId": "01HXYZ1234567890ABCDEF",
  "provider": "apify",
  "endpoint": "/apidojo/tweet-scraper",
  "status": "READY",
  "price": {
    "type": "PER_CALL",
    "amount": { "value": 0.003, "currency": "USD" }
  },
  "createdAt": "2026-03-28T10:30:00.000Z"
}
```

## Status vs Provider HTTP Status

Every completed run has two independent indicators:

1. **`status`** — the run lifecycle. `"COMPLETED"` means the provider was called and responded. `"FAILED"` means an infrastructure error (our fault). `"BLOCKED"` means a control gate rejected the run before execution. `"STOPPED"` means the run was stopped by request. `"TIMED_OUT"` means the run exceeded its time budget.
2. **`providerResponse.httpStatus`** — the provider's HTTP response code. `200` = data returned. `404` = no match. `429` = rate limited. `500` = provider error.

A run with `status: "COMPLETED"` and `providerResponse.httpStatus: 404` is normal — the run completed, the provider just found no data. Provider errors are not charged.

See [Status vs Provider HTTP Status](/docs/api/runs/get#status-vs-provider-http-status) for the full reference.

## Polling for Results

For async runs (`202` response), poll [`GET /v1/runs/:runId`](/docs/api/runs/get) to check status and retrieve results. Most runs complete within 1–120 seconds.

When polling, check two things:

1. **`status`** — wait until a terminal status: `"COMPLETED"`, `"FAILED"`, `"BLOCKED"`, `"STOPPED"`, or `"TIMED_OUT"`
2. **`providerResponse.httpStatus`** — once completed, check if the provider returned a success (2xx) or error (4xx/5xx)

## Next Step

Use [`GET /v1/runs/:runId`](/docs/api/runs/get) to retrieve run results.


# Get Run
Source: https://monid.ai/docs/api/runs/get

Get the status and results of a specific run.

```text theme={null}
GET /v1/runs/:runId
```

Get the status and results of a specific run.

## Headers

| Header           | Required | Description                                                                                                                                                                   |
| ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Authorization`  | Yes      | `Bearer <api-key>`                                                                                                                                                            |
| `x-workspace-id` | No       | Only needed with OAuth/JWT tokens without an org context — with a Monid API key the workspace is bound to the key. See [`GET /v1/auth/workspaces`](/docs/api/auth/workspaces) |

## Path Parameters

| Parameter | Type   | Description           |
| --------- | ------ | --------------------- |
| `runId`   | string | The run ID to look up |

## Example Request

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.monid.ai/v1/runs/01HXYZ1234567890ABCDEF" \
    -H "Authorization: Bearer monid_live_..."
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch(
    "https://api.monid.ai/v1/runs/01HXYZ1234567890ABCDEF",
    {
      headers: {
        Authorization: "Bearer monid_live_...",
      },
    },
  );
  ```
</CodeGroup>

## 200 OK

| Field              | Type                 | Description                                                             |
| ------------------ | -------------------- | ----------------------------------------------------------------------- |
| `runId`            | string               | Run identifier                                                          |
| `caller`           | string               | Prefixed caller id (e.g. `USER#<userId>`)                               |
| `provider`         | string               | Provider slug                                                           |
| `providerName`     | string \| undefined  | Provider display name                                                   |
| `endpoint`         | string               | Endpoint path                                                           |
| `status`           | string               | Run status                                                              |
| `stoppable`        | boolean \| undefined | Whether the run may be stopped (present only for non-terminal runs)     |
| `reason`           | string \| undefined  | `BLOCKED` only — why the control gate rejected the run                  |
| `controls`         | array \| undefined   | `BLOCKED` only — the blocking control(s)                                |
| `input`            | object               | Input parameters                                                        |
| `output`           | any \| null          | Provider output data (terminal runs only)                               |
| `providerResponse` | object \| undefined  | Provider response metadata (incl. `httpStatus`)                         |
| `price`            | object               | Endpoint pricing (`amount` is `{ "value": number, "currency": "USD" }`) |
| `cost`             | object \| undefined  | Actual cost charged                                                     |
| `billedUnits`      | number \| undefined  | Units of the price's billing unit consumed                              |
| `resultCount`      | number \| undefined  | Deprecated alias of `billedUnits`                                       |
| `resources`        | array \| undefined   | Provider resources created by this run                                  |
| `hints`            | object \| undefined  | Ready-to-use next-step commands                                         |
| `createdAt`        | string               | ISO 8601 timestamp                                                      |
| `startedAt`        | string \| undefined  | When execution started                                                  |
| `completedAt`      | string \| undefined  | When execution finished                                                 |

### 403 Forbidden

Returned when the run belongs to a different workspace than the caller's.

## Status vs Provider HTTP Status

Every run has two independent indicators:

1. **`status`** — the run lifecycle status. Did the run itself complete?
2. **`providerResponse.httpStatus`** — the provider's HTTP response code. Did the data provider return good data?

### Run Status

| Status      | Meaning                                                                   |
| ----------- | ------------------------------------------------------------------------- |
| `READY`     | Queued, waiting to start                                                  |
| `RUNNING`   | Actively executing                                                        |
| `STOPPING`  | Stop requested, shutting down (transient)                                 |
| `COMPLETED` | Run finished — the provider was called and responded                      |
| `FAILED`    | Infrastructure failure — pipeline crash or internal error (our fault)     |
| `BLOCKED`   | Rejected by a control gate before execution (see `reason` and `controls`) |
| `STOPPED`   | Stopped by request before completing (zero-billed)                        |
| `TIMED_OUT` | Ran past its time budget (terminal; distinct from `FAILED`)               |

### Provider HTTP Status

When a run is `COMPLETED`, check `providerResponse.httpStatus`:

| HTTP Status | Meaning                                           |
| ----------- | ------------------------------------------------- |
| `200`       | Success — `output` contains results               |
| `400`       | Bad request — invalid parameters sent to provider |
| `404`       | Not found — no match for the query                |
| `429`       | Rate limited — provider throttled the request     |
| `500`       | Provider error — the provider's service failed    |

Provider errors are **not charged** — `cost.value` will be `0`.

## Caching

Terminal runs include `Cache-Control: private, max-age=60` (60 seconds). Running runs are not cached.


# List Runs
Source: https://monid.ai/docs/api/runs/list

List runs for your workspace.

```text theme={null}
GET /v1/runs
```

List runs for your workspace with cursor-based pagination.

## Headers

| Header           | Required | Description                                                                                                                                                                   |
| ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Authorization`  | Yes      | `Bearer <api-key>`                                                                                                                                                            |
| `x-workspace-id` | No       | Only needed with OAuth/JWT tokens without an org context — with a Monid API key the workspace is bound to the key. See [`GET /v1/auth/workspaces`](/docs/api/auth/workspaces) |

## Query Parameters

| Parameter | Type   | Default | Description                                        |
| --------- | ------ | ------- | -------------------------------------------------- |
| `limit`   | number | 10      | Maximum runs to return (1–100)                     |
| `status`  | string | —       | Filter by run status (e.g. `RUNNING`, `COMPLETED`) |
| `cursor`  | string | —       | Pagination cursor from a previous response         |

## Example Request

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.monid.ai/v1/runs?limit=10" \
    -H "Authorization: Bearer monid_live_..."
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch("https://api.monid.ai/v1/runs?limit=10", {
    headers: {
      Authorization: "Bearer monid_live_...",
    },
  });
  ```

  ```python Python theme={null}
  import requests

  res = requests.get(
      "https://api.monid.ai/v1/runs",
      headers={
          "Authorization": "Bearer monid_live_...",
      },
      params={"limit": 10},
  )
  ```
</CodeGroup>

## 200 OK

| Field                      | Type                 | Description                                                                                             |
| -------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------- |
| `items`                    | array                | List of run summaries                                                                                   |
| `items[].runId`            | string               | Run identifier                                                                                          |
| `items[].caller`           | string               | Prefixed caller id (e.g. `USER#<userId>`)                                                               |
| `items[].provider`         | string               | Provider slug                                                                                           |
| `items[].providerName`     | string \| undefined  | Provider display name                                                                                   |
| `items[].endpoint`         | string               | Endpoint path                                                                                           |
| `items[].status`           | string               | Run status: `READY`, `RUNNING`, `STOPPING`, `COMPLETED`, `FAILED`, `BLOCKED`, `STOPPED`, or `TIMED_OUT` |
| `items[].stoppable`        | boolean \| undefined | Whether the run may be stopped (non-terminal runs only)                                                 |
| `items[].providerResponse` | object \| undefined  | Provider response metadata (incl. `httpStatus`)                                                         |
| `items[].price`            | object               | Endpoint pricing (`amount` is `{ "value": number, "currency": "USD" }`)                                 |
| `items[].cost`             | object \| undefined  | Actual cost charged                                                                                     |
| `items[].billedUnits`      | number \| undefined  | Units of the price's billing unit consumed                                                              |
| `items[].resultCount`      | number \| undefined  | Deprecated alias of `billedUnits`                                                                       |
| `items[].createdAt`        | string               | ISO 8601 timestamp                                                                                      |
| `items[].startedAt`        | string \| undefined  | When execution started                                                                                  |
| `items[].completedAt`      | string \| undefined  | When execution finished                                                                                 |
| `cursor`                   | string \| null       | Next-page cursor. `null` if last page                                                                   |

### Example Response

```json theme={null}
{
  "items": [
    {
      "runId": "01HXYZ1234567890ABCDEF",
      "caller": "USER#user_abc123",
      "provider": "apify",
      "providerName": "Apify",
      "endpoint": "/apidojo/tweet-scraper",
      "status": "COMPLETED",
      "providerResponse": { "httpStatus": 200 },
      "price": { "type": "PER_CALL", "amount": { "value": 0.003, "currency": "USD" } },
      "cost": { "value": 0.003, "currency": "USD" },
      "billedUnits": 1,
      "createdAt": "2026-03-28T10:30:00.000Z",
      "startedAt": "2026-03-28T10:30:00.000Z",
      "completedAt": "2026-03-28T10:30:01.000Z"
    }
  ],
  "cursor": null
}
```


# Stop Run
Source: https://monid.ai/docs/api/runs/stop

Stop a running run.

```text theme={null}
POST /v1/runs/:runId/stop
```

Stop a run that is `READY` or `RUNNING`. Stopping is asynchronous: the request is acknowledged with `202` and status `STOPPING`; poll [`GET /v1/runs/:runId`](/docs/api/runs/get) for the terminal state.

## Headers

| Header           | Required | Description                                                                                                                                                                   |
| ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Authorization`  | Yes      | `Bearer <api-key>`                                                                                                                                                            |
| `x-workspace-id` | No       | Only needed with OAuth/JWT tokens without an org context — with a Monid API key the workspace is bound to the key. See [`GET /v1/auth/workspaces`](/docs/api/auth/workspaces) |

## Path Parameters

| Parameter | Type   | Description        |
| --------- | ------ | ------------------ |
| `runId`   | string | The run ID to stop |

## Example Request

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST "https://api.monid.ai/v1/runs/01HXYZ1234567890ABCDEF/stop" \
    -H "Authorization: Bearer monid_live_..."
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch(
    "https://api.monid.ai/v1/runs/01HXYZ1234567890ABCDEF/stop",
    {
      method: "POST",
      headers: {
        Authorization: "Bearer monid_live_...",
      },
    },
  );
  ```
</CodeGroup>

## 202 Accepted

The stop request was accepted. The run transitions to `STOPPING` and settles asynchronously — poll [`GET /v1/runs/:runId`](/docs/api/runs/get) for the terminal state.

```json theme={null}
{
  "runId": "01HXYZ1234567890ABCDEF",
  "status": "STOPPING",
  "message": "Stop requested"
}
```

## 409 Conflict

Returned when the run cannot be stopped:

* The run is already terminal (`COMPLETED`, `FAILED`, `BLOCKED`, `STOPPED`, `TIMED_OUT`)
* The endpoint does not support stopping (`stoppable: false` on the run)

A `403` is returned if the run belongs to a different workspace.

<Note>
  The settlement depends on the endpoint's pricing model: runs on **metered** endpoints bill for the usage accrued before the stop and settle as `COMPLETED`; all other stopped runs settle as `STOPPED` and are zero-billed.
</Note>


# List Activities
Source: https://monid.ai/docs/api/wallet/activities

List wallet transactions.

```text theme={null}
GET /v1/wallet/activities
```

List the wallet's top-up and credit history with cursor-based pagination — prepaid top-ups and credits (promotional, manual). Run charges are not included; see [`GET /v1/runs`](/docs/api/runs/list) for per-run costs.

## Headers

| Header           | Required | Description                                              |
| ---------------- | -------- | -------------------------------------------------------- |
| `Authorization`  | Yes      | `Bearer <api-key>`                                       |
| `x-workspace-id` | No       | Only needed with OAuth/JWT tokens without an org context |

## Query Parameters

| Parameter | Type   | Default | Description          |
| --------- | ------ | ------- | -------------------- |
| `limit`   | number | 25      | Maximum items (1–25) |
| `cursor`  | string | —       | Pagination cursor    |

## 200 OK

| Field               | Type                | Description                               |
| ------------------- | ------------------- | ----------------------------------------- |
| `items`             | array               | Activity items                            |
| `items[].id`        | string              | Activity ID                               |
| `items[].type`      | string \| undefined | Activity type (e.g. `"Top-Up"`)           |
| `items[].amount`    | number              | Amount in dollars (non-negative float)    |
| `items[].currency`  | string              | ISO currency code                         |
| `items[].expiredAt` | string \| undefined | When the activity expires (if applicable) |
| `items[].createdAt` | string \| undefined | When the activity was created             |
| `cursor`            | string \| null      | Next-page cursor. `null` if last page     |

```json theme={null}
{
  "items": [
    {
      "id": "act_01HXYZ...",
      "type": "Top-Up",
      "amount": 10,
      "currency": "USD",
      "createdAt": "2026-03-28T10:30:15.000Z"
    }
  ],
  "cursor": null
}
```

## 503 Service Unavailable

Returned when the wallet is not active.


# Get Balance
Source: https://monid.ai/docs/api/wallet/balance

Get the current wallet balance.

```text theme={null}
GET /v1/wallet/balance
```

Get the current wallet balance for your workspace.

## Headers

| Header           | Required | Description                                              |
| ---------------- | -------- | -------------------------------------------------------- |
| `Authorization`  | Yes      | `Bearer <api-key>`                                       |
| `x-workspace-id` | No       | Only needed with OAuth/JWT tokens without an org context |

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.monid.ai/v1/wallet/balance" \
    -H "Authorization: Bearer monid_live_..."
  ```
</CodeGroup>

## 200 OK

| Field     | Type   | Description                                                                       |
| --------- | ------ | --------------------------------------------------------------------------------- |
| `balance` | object | Available balance as `{ "value": number, "currency": "USD" }`. It may be negative |
| `held`    | object | Funds held for in-flight runs, same shape                                         |

```json theme={null}
{
  "balance": { "value": 2.85, "currency": "USD" },
  "held": { "value": 0.10, "currency": "USD" }
}
```

## 503 Service Unavailable

Returned with a `walletStatus` field when the wallet is not active.


# monid discover
Source: https://monid.ai/docs/cli/discover

Search for data endpoints using natural language.

Search for data endpoints using natural language.

## Usage

```bash theme={null}
monid discover -q <query> [--limit <limit>] [--json]
```

## Flags

| Flag                  | Type    | Required | Description                                   |
| --------------------- | ------- | -------- | --------------------------------------------- |
| `-q, --query <query>` | string  | Yes      | A short natural language search query         |
| `--limit <limit>`     | number  | No       | Maximum number of results (default 5, max 40) |
| `-j, --json`          | boolean | No       | Output raw JSON                               |

## Examples

```bash theme={null}
# Search for Twitter-related endpoints
monid discover -q "twitter posts"

# Search with a limit
monid discover -q "linkedin profiles" --limit 3

# Get raw JSON output
monid discover -q "amazon product reviews" --json
```

## Output

Returns a list of endpoints matching the query:

```text theme={null}
Provider   Endpoint                       Price         Description
apify      /apidojo/tweet-scraper         $0.003/call   Scrape tweets by search...
apify      /apidojo/twitter-user-scraper  $0.003/call   Scrape Twitter user pro...
```

With the `--json` flag, the full JSON response is printed:

```json theme={null}
{
  "results": [
    {
      "provider": "apify",
      "providerName": "Apify",
      "endpoint": "/apidojo/tweet-scraper",
      "description": "Scrape tweets by search terms, hashtags, or user handles",
      "score": 0.87,
      "tags": ["twitter", "social-media"],
      "scoreBreakdown": { "querierScore": 0.82 },
      "price": {
        "type": "PER_CALL",
        "amount": { "value": 0.003, "currency": "USD" }
      }
    }
  ],
  "query": "twitter posts",
  "count": 2
}
```

## Tips

* **Keep queries short and focused.** Noun phrases like `"twitter posts"` or `"amazon product prices"` work better than full sentences.
* **Break complex requests into smaller pieces.** If you need data from multiple sources, discover each separately.
* **The endpoint catalog grows continuously.** Always discover rather than assuming what's available.

## Next Steps

After discovering endpoints, use [`monid inspect`](/docs/cli/inspect) to see the full input schema before running.


# examples
Source: https://monid.ai/docs/cli/examples

Complete end-to-end examples using the Monid CLI.

Complete end-to-end examples using the Monid CLI.

<AccordionGroup>
  <Accordion title="Search Twitter for recent AI posts">
    ```bash theme={null}
    # 1. Discover Twitter endpoints
    monid discover -q "twitter posts"

    # 2. Inspect the tweet scraper to see input schema
    monid inspect -p apify -e /apidojo/tweet-scraper

    # 3. Run with a small limit
    monid run -p apify -e /apidojo/tweet-scraper \
      -i '{"searchTerms":["AI"],"maxItems":10}'
    # → Run ID: 01HXYZ...

    # 4. Get the results
    monid runs get -r 01HXYZ... -o ai_tweets.json
    ```
  </Accordion>

  <Accordion title="Compare data across platforms (Twitter + LinkedIn)">
    Break the request into separate queries — one per platform.

    ```bash theme={null}
    # 1. Discover endpoints for each platform
    monid discover -q "twitter posts"
    monid discover -q "linkedin posts"

    # 2. Inspect each to learn their input schemas
    monid inspect -p apify -e /apidojo/tweet-scraper
    monid inspect -p apify -e /harvestapi/linkedin-post-search

    # 3. Run both
    monid run -p apify -e /apidojo/tweet-scraper \
      -i '{"searchTerms":["AI"],"maxItems":10}'
    # → Run ID: 01H_TW...

    monid run -p apify -e /harvestapi/linkedin-post-search \
      -i '{"keywords":"AI","maxResults":10}'
    # → Run ID: 01H_LI...

    # 4. Get results for each
    monid runs get -r 01H_TW... -o twitter_ai.json
    monid runs get -r 01H_LI... -o linkedin_ai.json
    ```
  </Accordion>

  <Accordion title="Scrape Google Maps reviews">
    ```bash theme={null}
    # 1. Discover Google Maps endpoints
    monid discover -q "google maps reviews"

    # 2. Inspect the scraper
    monid inspect -p apify -e /damilo/google-maps-scraper

    # 3. Create an input file for complex parameters
    cat > params.json << 'EOF'
    {
      "searchStringsArray": ["restaurants in San Francisco"],
      "maxReviews": 10,
      "language": "en"
    }
    EOF

    # 4. Run with input from file
    monid run -p apify -e /damilo/google-maps-scraper -i @params.json
    # → Run ID: 01HGEO...

    # 5. Get the results
    monid runs get -r 01HGEO... -o reviews.json
    ```
  </Accordion>
</AccordionGroup>


# monid inspect
Source: https://monid.ai/docs/cli/inspect

Get full details for a specific data endpoint.

Get full details for a specific data endpoint, including input schema, pricing, and documentation.

## Usage

```bash theme={null}
monid inspect -p <provider> -e <endpoint> [--json]
```

## Flags

| Flag                        | Type    | Required | Description                                    |
| --------------------------- | ------- | -------- | ---------------------------------------------- |
| `-p, --provider <provider>` | string  | Yes      | Provider slug (e.g., `apify`)                  |
| `-e, --endpoint <endpoint>` | string  | Yes      | Endpoint path (e.g., `/apidojo/tweet-scraper`) |
| `-j, --json`                | boolean | No       | Output raw JSON                                |

## Examples

```bash theme={null}
# Inspect a Twitter scraper
monid inspect -p apify -e /apidojo/tweet-scraper

# Inspect a Google Maps scraper
monid inspect -p apify -e /damilo/google-maps-scraper

# Get raw JSON output
monid inspect -p apify -e /apidojo/tweet-scraper --json
```

## Output

The inspect command displays:

* **Provider and endpoint name**
* **Description** — what the endpoint does
* **Summary** — detailed overview (when available)
* **Input schema** — JSON schema of accepted parameters
* **Pricing** — type (PER\_CALL or PER\_RESULT), amount, flat fee, and notes
* **Documentation URL** — link to the provider's docs
* **Usage examples** — ready-to-use CLI and API commands

Example output:

```text theme={null}
Provider:    apify
Endpoint:    /apidojo/tweet-scraper
Description: Scrape tweets by search terms, hashtags, or user handles

Price:
  Type:   PER_CALL
  Amount: $0.003

Input Schema:
  {
    "searchTerms": ["string"],
    "maxItems": "number",
    "sort": "string"
  }

Documentation: https://apify.com/apidojo/tweet-scraper

Usage:
  CLI: monid run -p apify -e /apidojo/tweet-scraper -i '{"searchTerms":["AI"]}'
  API: POST /v1/run {"provider":"apify","endpoint":"/apidojo/tweet-scraper","input":{...}}
```

<Tip>
  Always inspect before running. The input schema tells you exactly what parameters the endpoint accepts — never guess.
</Tip>

## Next Steps

After inspecting an endpoint, use [`monid run`](/docs/cli/run) to execute it.


# monid keys activate
Source: https://monid.ai/docs/cli/keys/activate

Switch the active API key.

Switch the active API key.

## Usage

```bash theme={null}
monid keys activate --label <name>
```

## Flags

| Flag                  | Type   | Required | Description                  |
| --------------------- | ------ | -------- | ---------------------------- |
| `-l, --label <label>` | string | Yes      | Label of the key to activate |

## Examples

```bash theme={null}
monid keys activate --label staging
```


# monid keys add
Source: https://monid.ai/docs/cli/keys/add

Add an API key to your local credential store.

Add an API key to your local credential store.

## Usage

```bash theme={null}
monid keys add --label <name> --key <key> [--json]
```

## Flags

| Flag                  | Type    | Required | Description                |
| --------------------- | ------- | -------- | -------------------------- |
| `-l, --label <label>` | string  | Yes      | A unique label for the key |
| `-k, --key <key>`     | string  | Yes      | The API key                |
| `-j, --json`          | boolean | No       | Output raw JSON            |

## Examples

```bash theme={null}
# Add a production key
monid keys add --label production --key monid_live_a1b2c3d4e5f6...

# Add a test key
monid keys add --label staging --key monid_test_x9y8z7w6v5u4...
```

## Behavior

* Label must be unique across stored keys
* The first key you add is automatically set as the active key


# monid keys list
Source: https://monid.ai/docs/cli/keys/list

List all locally stored API keys.

List all API keys stored locally on your machine.

## Usage

```bash theme={null}
monid keys list [--json]
```

## Output

```text theme={null}
Label        Key                  Added               Active
production   monid_live_a1b2****  2026-01-15 10:00    *
staging      monid_test_x9y8****  2026-01-20 14:30
```

The active key (marked with `*`) is used for all API calls.


# monid keys remove
Source: https://monid.ai/docs/cli/keys/remove

Remove an API key from your local credential store.

Remove an API key from your local credential store.

## Usage

```bash theme={null}
monid keys remove --label <name> [--force] [--json]
```

## Flags

| Flag                  | Type    | Required | Description                |
| --------------------- | ------- | -------- | -------------------------- |
| `-l, --label <label>` | string  | Yes      | Label of the key to remove |
| `--force`             | boolean | No       | Skip confirmation prompt   |
| `-j, --json`          | boolean | No       | Output raw JSON            |

## Behavior

* If the removed key was the active key, it's deactivated
* This only removes the key locally — it does not revoke the key on the server

<Tip>
  To revoke a key on the server (so it can no longer be used for API calls), use the [Monid web app](https://app.monid.ai/access/api-keys).
</Tip>


# CLI Overview
Source: https://monid.ai/docs/cli/overview

The Monid CLI lets you discover, inspect, and run data endpoints from the command line.

The Monid CLI lets you discover, inspect, and run data endpoints from the command line.

## Installation

```bash theme={null}
npm install -g @monid-ai/cli
```

Verify:

```bash theme={null}
monid --version
```

## Setup

### 1. Get an API Key

Go to [https://app.monid.ai](https://app.monid.ai) to create an account if you don't have one. Then go to [https://app.monid.ai/access/api-keys](https://app.monid.ai/access/api-keys) to create an API key. **Copy the key — it is only shown once.**

### 2. Add the Key

```bash theme={null}
monid keys add --label main --key <your-api-key>
```

The first key you add is automatically set as the active key.

### 3. Switch Active Key

If you have multiple keys, switch between them:

```bash theme={null}
monid keys activate --label <name>
```

## Example Workflow

```bash theme={null}
# 1. Discover endpoints for your data need
monid discover -q "twitter posts about AI"

# 2. Inspect an endpoint to see its input schema and pricing
monid inspect -p apify -e /apidojo/tweet-scraper

# 3. Run the endpoint
monid run -p apify -e /apidojo/tweet-scraper \
  -i '{"searchTerms":["AI"],"maxItems":10}'

# 4. Get the results
monid runs get -r <run-id> -o tweets.json
```

## Global Flags

All data commands support:

| Flag         | Description                                                                                                          |
| ------------ | -------------------------------------------------------------------------------------------------------------------- |
| `-j, --json` | Output raw JSON instead of formatted text. Suppresses spinners and colors. Useful for piping into `jq` or scripting. |
| `--help`     | Show help text for the command                                                                                       |

## Polling Strategies

Endpoint execution times vary widely depending on the endpoint and data volume. The recommended approach is to run without `--wait` and poll separately:

```bash theme={null}
# Start the run (returns immediately with a run ID)
monid run -p apify -e /apidojo/tweet-scraper -i '{"searchTerms":["AI"]}'
# → Run ID: 01HXYZ...

# Poll for results
monid runs get -r 01HXYZ... -o results.json
```

For blocking use cases, you can use `--wait` which polls with automatic exponential backoff until the run completes:

```bash theme={null}
monid run -p apify -e /apidojo/tweet-scraper \
  -i '{"searchTerms":["AI"]}' --wait -o results.json
```

## Environment Variables

| Variable             | Description                    |
| -------------------- | ------------------------------ |
| `MONID_API_BASE_URL` | Override the API base URL      |
| `XDG_CONFIG_HOME`    | Override config directory base |
| `NO_COLOR`           | Disable ANSI color codes       |

## Commands

### Endpoints

| Command                                | Description               |
| -------------------------------------- | ------------------------- |
| [`monid discover`](/docs/cli/discover) | Search for data endpoints |
| [`monid inspect`](/docs/cli/inspect)   | Get full endpoint details |
| [`monid run`](/docs/cli/run)           | Execute a data endpoint   |

### Runs

| Command                                  | Description                    |
| ---------------------------------------- | ------------------------------ |
| [`monid runs list`](/docs/cli/runs/list) | List recent runs               |
| [`monid runs get`](/docs/cli/runs/get)   | Get a run's status and results |
| [`monid runs stop`](/docs/cli/runs/stop) | Stop a queued or running run   |

### Keys & Access

| Command                                          | Description                  |
| ------------------------------------------------ | ---------------------------- |
| [`monid keys list`](/docs/cli/keys/list)         | List locally stored API keys |
| [`monid keys add`](/docs/cli/keys/add)           | Add an API key               |
| [`monid keys activate`](/docs/cli/keys/activate) | Switch the active API key    |
| [`monid keys remove`](/docs/cli/keys/remove)     | Remove an API key            |

### Examples

See [Examples](/docs/cli/examples) for complete end-to-end workflows.


# monid run
Source: https://monid.ai/docs/cli/run

Execute a data endpoint and retrieve results.

Execute a data endpoint and retrieve results.

For providers which are executed synchronously (e.g. People Data Labs), they return the results immediately; for others (e.g. Apify), the server will return 202 with a run ID and processes the request in the background.

## Usage

```bash theme={null}
monid run -p <provider> -e <endpoint> -i <input> [--wait [timeout]] [-o <file>] [--json]
```

## Flags

| Flag                        | Type    | Required | Description                                                     |
| --------------------------- | ------- | -------- | --------------------------------------------------------------- |
| `-p, --provider <provider>` | string  | Yes      | Provider slug                                                   |
| `-e, --endpoint <endpoint>` | string  | Yes      | Endpoint path                                                   |
| `-i, --input <input>`       | string  | Yes      | Input as inline JSON or `@path/to/file.json`                    |
| `-f, --input-file <path>`   | string  | No       | Read input from a JSON file (alternative to `-i @file`)         |
| `-w, --wait [timeout]`      | number  | No       | Wait for completion. Optional timeout in seconds (default: 300) |
| `-o, --output <path>`       | string  | No       | Save output to a file                                           |
| `-j, --json`                | boolean | No       | Output raw JSON                                                 |

## Examples

### Run and poll separately (recommended)

```bash theme={null}
monid run -p apify -e /apidojo/tweet-scraper \
  -i '{"searchTerms":["AI"],"maxItems":10}'
# → Run ID: 01HXYZ...

monid runs get -r 01HXYZ... -o tweets.json
```

### Run with wait

```bash theme={null}
monid run -p apify -e /apidojo/tweet-scraper \
  -i '{"searchTerms":["AI"],"maxItems":10}' \
  --wait -o tweets.json
```

### Input from file

```bash theme={null}
monid run -p apify -e /damilo/google-maps-scraper \
  -i @params.json -o results.json
```

### With custom timeout

```bash theme={null}
monid run -p apify -e /apidojo/tweet-scraper \
  -i '{"searchTerms":["AI"],"maxItems":50}' \
  --wait 120 -o tweets.json
```

## Output

### Sync providers

For sync providers, the result is returned immediately — no polling needed:

```text theme={null}
Run ID:    01HXYZ...
Status:    COMPLETED
Response:  HTTP 200
Provider:  pdl
Endpoint:  /person/enrich
Price:     $0.003/call
Cost:      $0.003
Created:   2026-03-28T10:30:00Z
Done:      2026-03-28T10:30:01Z

{
  "full_name": "John Doe",
  "linkedin_url": "linkedin.com/in/johndoe"
}
```

### Async providers

For async providers, the run starts in the background. Poll with `monid runs get` or use `--wait`:

```text theme={null}
Run started
  Run ID:   01HXYZ...
  Provider: apify
  Endpoint: /apidojo/tweet-scraper
  Status:   READY
  Price:    $0.003/call

Poll with: monid runs get -r 01HXYZ...
```

With `--wait`, the CLI polls automatically until the run completes:

```text theme={null}
Run ID:    01HXYZ...
Status:    COMPLETED
Response:  HTTP 200
Provider:  apify
Endpoint:  /apidojo/tweet-scraper
Price:     $0.003/call
Cost:      $0.003
Created:   2026-03-28T10:30:00Z
Done:      2026-03-28T10:30:15Z

Results saved to tweets.json
```

### Provider errors

If the provider returned an error, the run still shows `Status: COMPLETED` (the run itself finished) but the `Response` line shows the provider's HTTP status:

```text theme={null}
Run ID:    01HXYZ...
Status:    COMPLETED
Response:  HTTP 404 — No match found for the given query
Provider:  pdl
Endpoint:  /person/enrich
Price:     $0.003/call
Cost:      $0.00
Created:   2026-03-28T10:30:00Z
Done:      2026-03-28T10:30:01Z
```

### Infrastructure errors

If Monid itself failed to execute the run, the status is `FAILED`:

```text theme={null}
Run ID:    01HXYZ...
Status:    FAILED
Provider:  apify
Endpoint:  /apidojo/tweet-scraper
Price:     $0.003/call
Cost:      $0.00
Created:   2026-03-28T10:30:00Z
Done:      2026-03-28T10:30:02Z

Error: An internal error occurred while processing this run.
```

## Status vs Provider HTTP Status

Every completed run has two independent indicators:

| Field        | What it tells you             | Example                                                  |
| ------------ | ----------------------------- | -------------------------------------------------------- |
| **Status**   | Did the run complete?         | `COMPLETED`, `FAILED`, `BLOCKED`, `STOPPED`, `TIMED_OUT` |
| **Response** | What did the provider return? | `HTTP 200`, `HTTP 404`, `HTTP 500`                       |

* `Status: COMPLETED` + `Response: HTTP 200` = success, data returned
* `Status: COMPLETED` + `Response: HTTP 404` = run finished, but provider found no data
* `Status: COMPLETED` + `Response: HTTP 500` = run finished, but provider had an error
* `Status: FAILED` = infrastructure error (our fault), no provider response
* `Status: BLOCKED` = rejected by a control gate before execution, no provider response
* `Status: STOPPED` = stopped by request before completing, zero-billed

See the full run status table in [`monid runs get`](/docs/cli/runs/get#run-status).

Provider errors (non-2xx responses) are not charged.

## Next Steps

* [`monid runs get`](/docs/cli/runs/get) — Check run status and retrieve results
* [`monid inspect`](/docs/cli/inspect) — Verify input schema before running


# monid runs get
Source: https://monid.ai/docs/cli/runs/get

Get the status and results of a specific run.

Get the status and results of a specific run.

## Usage

```bash theme={null}
monid runs get -r <run-id> [--wait [timeout]] [-o <file>] [--json]
```

## Flags

| Flag                   | Type    | Required | Description                                                     |
| ---------------------- | ------- | -------- | --------------------------------------------------------------- |
| `-r, --run-id <runId>` | string  | Yes      | The run ID to look up                                           |
| `-w, --wait [timeout]` | number  | No       | Wait for completion. Optional timeout in seconds (default: 300) |
| `-o, --output <path>`  | string  | No       | Save output to a file                                           |
| `-j, --json`           | boolean | No       | Output raw JSON                                                 |

## Examples

```bash theme={null}
# Check current status
monid runs get -r 01HXYZ...

# Wait for completion and save results
monid runs get -r 01HXYZ... --wait -o results.json

# Wait with custom timeout
monid runs get -r 01HXYZ... --wait 60
```

### Example Output

The output shows both **Status** (run lifecycle) and **Response** (provider HTTP status):

```text theme={null}
Run ID:    01HXYZ...
Status:    COMPLETED
Response:  HTTP 200
Provider:  pdl
Endpoint:  /person/enrich
Price:     $0.003/call
Cost:      $0.003
Created:   2026-03-28T10:30:00Z
Done:      2026-03-28T10:30:01Z
```

When the provider returned an error:

```text theme={null}
Run ID:    01HXYZ...
Status:    COMPLETED
Response:  HTTP 404 — No match found for the given query
Provider:  pdl
Endpoint:  /person/enrich
Price:     $0.003/call
Cost:      $0.00
Created:   2026-03-28T10:30:00Z
Done:      2026-03-28T10:30:01Z
```

## Status vs Provider HTTP Status

Every run has two independent indicators:

1. **Run status** — did the run itself complete?
2. **Provider HTTP status** — what did the data provider return?

### Run Status

| Status      | Meaning                                                               |
| ----------- | --------------------------------------------------------------------- |
| `READY`     | Queued, waiting to start                                              |
| `RUNNING`   | Actively executing                                                    |
| `STOPPING`  | Stop requested, shutting down (transient)                             |
| `COMPLETED` | Run finished — the provider was called and responded                  |
| `FAILED`    | Infrastructure failure — pipeline crash or internal error (our fault) |
| `BLOCKED`   | Rejected by a control gate before execution                           |
| `STOPPED`   | Stopped by request before completing (zero-billed)                    |
| `TIMED_OUT` | Ran past its time budget (terminal; distinct from `FAILED`)           |

### Provider HTTP Status

When a run is `COMPLETED`, the provider's HTTP status code tells you whether the data request succeeded:

| HTTP Status | Meaning                                           |
| ----------- | ------------------------------------------------- |
| `200`       | Success — `output` contains results               |
| `400`       | Bad request — invalid parameters sent to provider |
| `404`       | Not found — no match for the query                |
| `429`       | Rate limited — provider throttled the request     |
| `500`       | Provider error — the provider's service failed    |

The provider HTTP status is available in `providerResponse.httpStatus` in the JSON response.

<Info>
  A run with `status: COMPLETED` and `providerResponse.httpStatus: 404` means the run completed normally, but the provider found no matching data. This is **not** a failure — it's a valid "no results" response. You are not charged for provider errors.
</Info>


# monid runs list
Source: https://monid.ai/docs/cli/runs/list

List recent runs.

List recent runs with cursor-based pagination.

## Usage

```bash theme={null}
monid runs list [--limit <limit>] [--cursor <cursor>] [--json]
```

## Flags

| Flag                | Type    | Required | Description                                |
| ------------------- | ------- | -------- | ------------------------------------------ |
| `--limit <limit>`   | number  | No       | Maximum number of runs to return           |
| `--cursor <cursor>` | string  | No       | Pagination cursor from a previous response |
| `-j, --json`        | boolean | No       | Output raw JSON                            |

## Examples

```bash theme={null}
# List recent runs
monid runs list

# List with a limit
monid runs list --limit 5

# Paginate
monid runs list --cursor <cursor-value>
```


# monid runs stop
Source: https://monid.ai/docs/cli/runs/stop

Stop a queued or running run.

Stop a run that is `READY` or `RUNNING`. Terminal runs (`COMPLETED`, `FAILED`, `BLOCKED`, `STOPPED`, `TIMED_OUT`) cannot be stopped, and endpoints that are not stoppable are rejected with a `409`.

Stopping is asynchronous: the command is acknowledged with status `STOPPING`, and the run then settles to a terminal status. Use [`monid runs get`](/docs/cli/runs/get) to confirm the final state.

## Usage

```bash theme={null}
monid runs stop -r <run-id> [--json]
```

## Flags

| Flag                   | Type    | Required | Description        |
| ---------------------- | ------- | -------- | ------------------ |
| `-r, --run-id <runId>` | string  | Yes      | The run ID to stop |
| `-j, --json`           | boolean | No       | Output raw JSON    |

## Examples

```bash theme={null}
monid runs stop -r 01HXYZ...
```

<Note>
  The settlement depends on the endpoint's pricing model: runs on **metered** endpoints bill for the usage accrued before the stop and settle as `COMPLETED`; all other stopped runs settle as `STOPPED` and are zero-billed.
</Note>


# Compare Products Using Customer-Review Evidence
Source: https://monid.ai/docs/examples/audience-research/review-insights

Use Monid to compare products using balanced review samples, recurring tradeoffs, and clearly labeled uncertainties.

Give your agent product URLs and what matters most to you. It uses Monid to collect a balanced review sample, separate variants, and return a recommendation grounded in cited reviews.

<Tip>
  **Example question:** Which of three electric coffee grinders under \$150 is easiest to live with day to day?
</Tip>

## Try it yourself (give it to your agent)

```text Prompt theme={null}
Use Monid to compare three electric coffee grinders under $150 using customer-review evidence.

Ask for the three Amazon product URLs, my country, brewing method, and whether noise, cleaning, counter space, or grind consistency matters most. My research budget is $2. Inspect the review tool's pricing and limit semantics; cap the collection instead of assuming a page limit means a review limit.

Collect a balanced sample across ratings and recent dates. Separate product variants, remove duplicate reviews, and group recurring tradeoffs. Include positive counterexamples instead of selecting only complaints. Treat review anecdotes as evidence of experiences, not a measured defect rate.

Return a recommendation for my priorities, a comparison of the main tradeoffs, source-linked review examples, sample sizes, and uncertainties. Mark prices as unverified if current listing prices were not retrieved. Report spend and do not purchase anything.
```

## Potential tools

* [**Amazon**](https://monid.ai/tools/amazon): Apify's `/web_wanderer/amazon-reviews-extractor` retrieves review text, ratings, variants, dates, and available verified-purchase metadata.

The agent compares the review evidence against your requirements.

## Example output

<Note>Names, counts, and details below are fictional. Real responses include actual sources, costs, and generated files.</Note>

> **For your priorities, I would shortlist Grinder B.** In the collected sample, reviewers more consistently described it as **easy to clean** and **compact enough to leave on the counter**.
>
> * **Grinder A:** Stronger praise for adjustment options, but several reviewers found daily cleaning fiddly.
> * **Grinder C:** Suitable for occasional use, although noise complaints appeared in **both positive and negative** reviews.
>
> These are patterns in the reviewed sample, **not measured reliability statistics**. I kept different product variants separate and included examples that contradict the main themes. Please confirm **current prices** before buying.


# Find TikTok Videos Outperforming a Creator's Baseline
Source: https://monid.ai/docs/examples/audience-research/tiktok-outliers

Use Monid to surface videos beating each creator's own median, with sample sizes, baselines, and testable hypotheses.

Give your agent a niche, country, and budget. It uses Monid to discover recent posts, calculate creator-relative baselines, and return outlier videos worth studying.

<Tip>
  **Example question:** Which videos are outperforming for small specialty-coffee creators this month?
</Tip>

## Try it yourself (give it to your agent)

```text Prompt theme={null}
Use Monid to find unusually strong TikTok videos from specialty-coffee creators with fewer than 100,000 followers, posted in the last 30 days.

Ask which country and language to focus on, and whether I care most about brewing tutorials, equipment reviews, or cafe content. My budget is $2. Inspect prices, cap the initial discovery set at 50 videos, and compare no more than five shortlisted creators initially.

For each shortlisted creator, retrieve a bounded sample of recent posts and compare each candidate video's views with that creator's median. Show sample size, post age, raw views, baseline, and outlier ratio. Do not treat a single snapshot as evidence of accelerating growth.

Return five videos worth studying, their source links, and testable ideas about the hook or format. Treat explanations as hypotheses, not proof of why a video succeeded. Report missing metrics, collection limits, and actual spend.
```

## Potential tools

* [**TikTok**](https://monid.ai/tools/tiktok): Apify's `/apidojo/tiktok-scraper` supports keyword/profile collection.
* **TikHub**: `/api/v1/tiktok/web/fetch_user_post` can retrieve creator history when the correct account identifier is available.

The agent calculates creator-relative baselines and outliers.

## Example output

<Note>Names, counts, and details below are fictional. Real responses include actual sources, costs, and generated files.</Note>

> **The strongest outlier was a side-by-side grinder demonstration.**
>
> * **Views:** 84,000
> * **Creator's recent median:** 7,000
> * **Outlier ratio:** 12× baseline across 20 sampled posts
>
> A second standout was a *"fix this sour espresso"* video. Its opening shows the failed result **before** explaining the adjustment, giving viewers a clear reason to continue.
>
> **Suggested experiment:** Test a visible before/after result in the first few seconds. That is a **hypothesis** based on these examples, not proof that the opening caused their performance.
>
> All five selections include links and baseline calculations. I could **not** assess growth velocity because no earlier snapshots were available.


# Produce a Short Audio Briefing From This Week's News
Source: https://monid.ai/docs/examples/creative-production/audio-briefing

Use Monid to research, script, and narrate a short weekly audio briefing with citations and cost reporting.

Give your agent a market, topics, and budget. It uses Monid to gather original sources, write a compact script, and generate narration only after you approve the plan.

<Tip>
  **Example question:** Can my agent make a three-minute audio briefing about this week's ecommerce news?
</Tip>

## Try it yourself (give it to your agent)

```text Prompt theme={null}
Use Monid to make a three-minute audio briefing about the most useful ecommerce developments from the last seven days.

Ask which market I work in, which topics matter most, the language, and whether I prefer a formal or conversational delivery. My total research-and-audio budget is $2. Inspect current search and speech-generation prices before paid calls.

Find original sources, remove syndicated duplicates, and select three stories with practical implications for a small online retailer. Write a concise script with source links and distinguish reported facts from your interpretation.

Show me the script, proposed permitted stock voice, and estimated audio cost before generating. After approval, create the narration and return the MP3, script, citations, voice/model settings, actual spend, and link-expiry information. Do not imitate a person without authorization, distribute the recording, or schedule recurring briefings.
```

## Potential tools

* [**TinyFish**](https://monid.ai/tools/tinyfish): `/search` and `/fetch` provide current-source research.
* [**Exa**](https://monid.ai/tools/exa): `/search` and `/contents` are an alternative for source research.
* [**ElevenLabs**](https://monid.ai/tools/elevenlabs): `/text-to-speech` generates narration after script approval.

The agent selects stories and writes the briefing.

## Example output

<Note>Names, counts, and details below are fictional. Real responses include actual sources, costs, and generated files.</Note>

> Your **three-minute ecommerce briefing** is ready, along with the approved script and source list.
>
> The episode covers **three developments**:
>
> * A marketplace policy change
> * A new checkout feature
> * A shipping-service update
>
> Each segment explains **what changed**, **who may be affected**, and **what a small retailer should check next**.
>
> I used the approved stock voice and kept the narration conversational. The response includes the **MP3**, the exact **voice/model settings**, and **actual research and generation costs**.
>
> **No recording was distributed** and **no recurring job was created**. Store the audio before its download link expires.


# Turn a Product Photo Into a Short Promo Video
Source: https://monid.ai/docs/examples/creative-production/product-video

Use Monid to generate one short vertical promo clip from a reference photo, with approval and cost reporting.

Give your agent an approved product photo and a budget. It uses Monid to generate one short reference-based clip, report exact costs, and remind you to verify product details.

<Tip>
  **Example question:** Can my agent turn a product photo into an eight-second vertical promotional video?
</Tip>

## Try it yourself (give it to your agent)

```text Prompt theme={null}
Use Monid to create one eight-second, 9:16 promotional video for a ceramic coffee mug from an approved product photo.

Ask me to provide the photo, confirm I have the right to use it, and specify the mug details that must stay unchanged. Ask whether the desired look is a cozy home kitchen or a premium studio setup. My maximum generation budget is $3.

Inspect a currently available reference-image video model, its restrictions, and pricing. Propose a simple shot: a slow camera move around the mug, gentle morning light, and no people or text overlays. Show the estimated cost and ask for approval before generating.

Return the playable clip, exact model and settings, generation cost, and any download-expiry information. Tell me to check the handle, proportions, color, and branding against the reference before approving more clips. Do not generate a batch, publish the asset, or promise perfect product consistency.
```

## Potential tools

* [**ByteDance**](https://monid.ai/tools/bytedance): `/v1/video/seedance-2.0` supports reference-based video generation.
* [**MiniMax**](https://monid.ai/tools/minimax): `/v1/image_generation` may help prepare an approved image if needed, but is not required when you already have a suitable product photo.

The agent selects settings, requests approval, and returns the generated asset.

## Example output

<Note>Names, counts, and details below are fictional. Real responses include actual sources, costs, and generated files.</Note>

> Your **eight-second vertical preview** is ready.
>
> The shot moves slowly around the mug on a kitchen counter, with soft morning light and **no text overlay**. I used your approved image as the reference and generated **only one clip**.
>
> **Before proceeding, compare:**
>
> * The handle and rim
> * Color and finish
> * Any logo or branding
>
> Generated video can change **small product details**.
>
> The response includes the video file, model settings, and **actual generation cost**. Download or store the clip before its temporary link expires. I have **not** published it or started any additional generations.


# Have Your Agent Make a Quick Phone Inquiry
Source: https://monid.ai/docs/examples/creative-production/repair-call

Use Monid to place one short, approved phone call on your behalf with AI disclosure, a transcript, and clear cost reporting.

Give your agent a phone number, a specific question, and a budget. It uses Monid to place one approved, disclosed call, returns what was actually confirmed, and separates one-off call costs from any recurring phone-number rental.

<Tip>
  **Example question:** Can my agent call my bike shop to ask whether it can fix a flat tire tomorrow?
</Tip>

## Try it yourself (give it to your agent)

```text Prompt theme={null}
Use Monid to help me call a bike shop and ask whether it can repair my flat tire tomorrow. This is one non-marketing inquiry, not a booking or purchase.

Ask for the shop's name and phone number, its location/timezone, my bike type, my preferred drop-off time, and which personal details I allow you to share. Confirm the date meant by tomorrow and an appropriate time to call.

Inspect the available phone tools and prices. My total budget is $5. If a new phone number is needed, explain its initial charge, recurring monthly cost, and release policy, and ask for approval before provisioning. Check AI disclosure and recording/transcription consent requirements; stop if they cannot be satisfied.

Show me the exact recipient and call instructions for approval before dialing. Identify yourself as an AI assistant calling on my behalf. Ask about repair availability, likely turnaround, and an estimated price. Keep it brief; do not book, authorize repairs, leave voicemail, redial, or send texts without approval.

Return what the shop actually confirmed, anything still unknown, the call outcome, an available consented transcript, and actual costs. Tell me whether a paid number remains active and ask whether to keep or release it.
```

## Potential tools

* [**Saperly**](https://monid.ai/tools/saperly): `/provision-numbers` creates a workspace-owned US phone number when needed; `/place-calls` starts the approved call; `/calls/{id}` and `/calls/{id}/transcript` retrieve status and transcript information.

The agent checks the result and separates a confirmed answer from an unanswered call. Phone-number rental can **recur until released**, so it requires explicit approval separately from call usage.

## Example output

<Note>Names, counts, and details below are fictional. Real responses include actual sources, costs, and generated files.</Note>

> **The shop can inspect your bike tomorrow morning.** They suggested dropping it off between **9 and 11**, but said the final repair time depends on the tire and whether parts are needed.
>
> They could **not confirm a final price** without seeing the bike. I did **not** book an appointment or authorize any repair.
>
> **Call details:**
>
> * **Duration:** 1 minute 40 seconds
> * **Call usage:** \$0.50
> * **New number initial charge:** \$2.00
> * **Total for this task:** \$2.50
>
> The approved transcript is available with the call details. Your number remains active and has a **\$2 monthly renewal**. Would you like me to request its release now, or keep it for future calls?


# Examples: See What Your Agent Can Do with Monid
Source: https://monid.ai/docs/examples/overview

Copyable prompts for common agent tasks across sales, research, SEO, audience insights, and creative production with Monid.

See what your agent can do with Monid. Pick a task, copy the prompt, and let your agent find the right tools. These examples assume Monid is already connected.

<Note>
  **Illustrative output, not a live result.** Names, counts, measurements, prices, and assets in sample responses are fictional. Real responses should include actual sources, costs, and generated files where applicable. Potential tools are examples of what an agent may select, not a fixed execution sequence.
</Note>

## Sales & Leads

<CardGroup>
  <Card title="Local Leads" icon="location-dot" href="/docs/examples/sales-leads/local-leads">
    Find independent local businesses that fit your services.
  </Card>

  <Card title="Verified Contacts" icon="envelope-circle-check" href="/docs/examples/sales-leads/verified-contacts">
    Discover and verify business emails for target-fit companies.
  </Card>
</CardGroup>

## Research & Briefings

<CardGroup>
  <Card title="Company Brief" icon="building" href="/docs/examples/research-briefings/company-brief">
    Prepare a one-page briefing before a partnership meeting.
  </Card>

  <Card title="YouTube Digest" icon="youtube" href="/docs/examples/research-briefings/youtube-digest">
    Summarize this week's videos on a topic with citations.
  </Card>
</CardGroup>

## SEO & Visibility

<CardGroup>
  <Card title="Content Opportunities" icon="magnifying-glass-chart" href="/docs/examples/seo-visibility/content-opportunities">
    Prioritize the next five pages or FAQs to publish.
  </Card>

  <Card title="AI Citations" icon="quote-left" href="/docs/examples/seo-visibility/ai-citations">
    Compare your brand's AI citation counts with competitors.
  </Card>
</CardGroup>

## Audience Research

<CardGroup>
  <Card title="TikTok Outliers" icon="tiktok" href="/docs/examples/audience-research/tiktok-outliers">
    Find videos outperforming a creator's own baseline.
  </Card>

  <Card title="Review Insights" icon="star-half-stroke" href="/docs/examples/audience-research/review-insights">
    Compare products using balanced customer-review evidence.
  </Card>
</CardGroup>

## Create & Communicate

<CardGroup>
  <Card title="Product Video" icon="film" href="/docs/examples/creative-production/product-video">
    Turn a product photo into a short vertical promotional clip.
  </Card>

  <Card title="Audio Briefing" icon="microphone" href="/docs/examples/creative-production/audio-briefing">
    Produce a short narrated briefing from this week's news.
  </Card>

  <Card title="Repair Call" icon="phone" href="/docs/examples/creative-production/repair-call">
    Place a quick, approved phone call to ask a specific question.
  </Card>
</CardGroup>


# Prepare a Company Brief Before a Partnership Meeting
Source: https://monid.ai/docs/examples/research-briefings/company-brief

Use Monid to build a one-page partnership briefing with dated sources, angles, and questions for the meeting.

Give your agent a company and your goals. It uses Monid to research the company, verify material claims, and produce a compact briefing you can bring into the meeting.

<Tip>
  **Example question:** What should I know before tomorrow's partnership meeting with a private company?
</Tip>

## Try it yourself (give it to your agent)

```text Prompt theme={null}
Use Monid to prepare a one-page briefing for a partnership meeting I have tomorrow.

First ask for the company name and website, what my business offers, the partnership I am considering, and any questions I already have. My research budget is $2. Inspect prices before paid calls and confirm the company's identity before enrichment.

Research what the company does, its customers and leadership, available funding information, and important news from the last six months. Check material claims against original sources where accessible. Separate confirmed facts, provider estimates, and your interpretation. Do not invent private revenue, valuation, or ownership details.

Return an executive summary, a dated list of important developments, three possible partnership angles, and five questions for the meeting. Include source links, uncertainties, and actual spend. Do not contact the company.
```

## Potential tools

* [**Akta**](https://monid.ai/tools/akta): `/v1/company/search` resolves the company; `/v1/company/enrichment` and `/v1/news` provide company info and news.
* [**Fundable**](https://monid.ai/tools/fundable): `/companies` and `/deals` add funding context.
* [**TinyFish**](https://monid.ai/tools/tinyfish): helps check original sources.

## Example output

<Note>Names, counts, and details below are fictional. Real responses include actual sources, costs, and generated files.</Note>

> **Meeting brief: Northstar Robotics**
>
> Northstar appears most relevant to your business as a **distribution partner** rather than a direct buyer. Its product pages emphasize warehouse operators, which overlaps with your existing customer base.
>
> **A useful opening:** Ask whether customers need reporting integrations after deployment. That could be a focused pilot for your analytics product.
>
> **Questions to prioritize:**
>
> * Who owns integrations?
> * What does a successful pilot look like?
> * Which customer segment should it serve?
> * What security review is required?
> * Who approves a commercial partnership?
>
> The brief includes dated sources for product and funding claims. I could **not verify current revenue or valuation**, so I have not used those figures in the recommendation.


# Digest This Week's YouTube Videos on a Topic
Source: https://monid.ai/docs/examples/research-briefings/youtube-digest

Use Monid to summarize this week's videos on a topic with transcripts, disagreements, and visual-only caveats.

Give your agent a topic and audience preference. It uses Monid to find recent videos, pull available transcripts, and synthesize practical lessons with clear citation coverage.

<Tip>
  **Example question:** What did this week's AI coding-agent videos actually teach, and where did the creators disagree?
</Tip>

## Try it yourself (give it to your agent)

```text Prompt theme={null}
Use Monid to create a briefing from up to 10 English-language YouTube videos about AI coding agents published in the last seven days.

Ask whether I want beginner tutorials, engineering deep dives, or product comparisons, and whether any channels should be included or excluded. My budget is $2. Inspect discovery and transcript prices, start with a small batch, and ask before expanding beyond the budget.

Find relevant videos, retrieve available transcripts, and remove duplicate videos and repeated claims. Summarize practical lessons, points of disagreement, and which videos are worth watching in full. Cite video links and timestamps when available.

Include a coverage list showing which videos had usable transcripts. Clearly identify conclusions that need visual inspection; do not claim to have watched demonstrations if only captions were available. Report failures and actual spend rather than silently replacing missing sources.
```

## Potential tools

* [**YouTube**](https://monid.ai/tools/youtube): Apify's `/streamers/youtube-scraper` discovers videos; `/starvibe/youtube-video-transcript` retrieves available transcripts.
* **TikHub**: `/api/v1/youtube/web_v2/get_video_info` can add video details.

The agent compares and synthesizes the retrieved material.

## Example output

<Note>Names, counts, and details below are fictional. Real responses include actual sources, costs, and generated files.</Note>

> I reviewed transcripts from **8 of 10 selected videos**. Two had no accessible captions.
>
> **Main takeaway:** The most useful demonstrations kept tasks small, supplied repository context, and required tests before accepting changes.
>
> **Where creators disagreed:** Some preferred a detailed upfront plan; others favored short implementation-and-test cycles. Their demonstrations used different task sizes, so the results are **not directly comparable**.
>
> **Worth watching:** *"Debugging an Agent's First Pull Request,"* especially the walkthrough beginning at **08:40**. The terminal interaction contains visual detail that a transcript summary cannot fully capture.
>
> The digest includes video links, timestamps, and a **separate list of unsupported or visual-only claims**.


# Find Local Leads for Your Services with Monid
Source: https://monid.ai/docs/examples/sales-leads/local-leads

Use Monid to shortlist independent local businesses that fit your services, with observable opportunities and public contact details.

Give your agent a target service, city, and budget. It uses Monid to surface fit-checked local prospects with public evidence, source links, and a spend report.

<Tip>
  **Example question:** Which 10 independent dental clinics in Austin should my web-design studio research as potential clients?
</Tip>

## Try it yourself (give it to your agent)

```text Prompt theme={null}
Use Monid to find up to 10 independent dental clinics in Austin, Texas, that could be a good fit for my web-design studio.

Before searching, ask which website services I sell, which clinics or chains to exclude, and how far outside Austin to look. My research budget is $2. Inspect current tool prices and use explicit result limits; ask before exceeding the budget.

Find candidates through business listings, then check their websites for observable opportunities relevant to my services, such as a missing online appointment-request link. Do not assume a clinic has a problem just because a page failed to load.

Return a ranked shortlist with the clinic's name, website, location, public business contact details, a specific reason it fits, and source links. Flag uncertain matches and missing information. Report actual spend. Do not contact clinics or buy personal contact details.
```

## Potential tools

* [**Maps & Places**](https://monid.ai/tools/maps): Apify's `/damilo/google-maps-scraper` finds businesses and public listing details.
* [**TinyFish**](https://monid.ai/tools/tinyfish): `/search` and `/fetch` help check their websites.

The agent compares the evidence against your services and ranks candidates.

## Example output

<Note>Names, counts, and details below are fictional. Real responses include actual sources, costs, and generated files.</Note>

> I found **10 clinics worth reviewing**. Two are especially relevant to your appointment-booking service:
>
> **Cedar Gate Dental:** The website lists a phone number for appointments, but I could not find an online appointment-request link on the pages reviewed.
>
> * **Suggested angle:** Make it easier for new patients to request a visit after hours.
>
> **Lakeview Family Dental:** The clinic has a dedicated new-patient page, but its booking link leads to a general contact form.
>
> * **Suggested angle:** A clearer new-patient booking flow.
>
> The shortlist includes each clinic's website, Maps listing, public contact channel, and supporting page. I excluded **3 chain locations** and left **1 ambiguous business match** unresolved. **No outreach was sent.**


# Find Verified Business Contacts for Target Companies
Source: https://monid.ai/docs/examples/sales-leads/verified-contacts

Use Monid to discover fit-matched companies and return verified work emails with clear deliverability status.

Give your agent a segment, size range, and budget. It uses Monid to discover target-fit companies, enrich a small set of leaders, and separate verified emails from catch-all or unknown results.

<Tip>
  **Example question:** Can I find verified work emails for sales leaders at 10 US B2B SaaS companies with 20-100 employees?
</Tip>

## Try it yourself (give it to your agent)

```text Prompt theme={null}
Use Monid to find one relevant sales leader at each of up to 10 US B2B SaaS companies with approximately 20-100 employees.

Ask which product segment to focus on, whether I want founders or sales executives, and which existing contacts or companies to exclude. My total budget is $3. Inspect the available tools and prices before paid calls.

Discover and qualify companies first. Enrich only the best-fit contacts, reuse any data I already have, and verify business-email deliverability where supported. Do not purchase personal emails or phone numbers. Do not use X or LinkedIn scraping.

Return each company, the contact's role, why they fit, their work email when available, and its exact verification status. Keep verified, catch-all, unknown, and no-match results separate. Include sources, missing fields, and actual spend. Return fewer than 10 rather than inventing contacts, and do not send messages.
```

## Potential tools

* [**Apollo**](https://monid.ai/tools/apollo): `/mixed_people/api_search`, `/organizations/enrich`, and `/people/match` support discovery and selected enrichment.
* [**Hunter**](https://monid.ai/tools/hunterio): `/email-finder` and `/email-verifier` help find and check business emails.

The agent stops enriching once it has enough qualified contacts.

## Example output

<Note>Names, counts, and details below are fictional. Real responses include actual sources, costs, and generated files.</Note>

> I qualified **10 companies** and found **7 work emails marked deliverable**. **2 were catch-all** addresses, and **1 company had no suitable contact**.
>
> **Avery Chen, VP of Sales at Northstar CRM:** Fits your customer-support SaaS segment and company-size range.
>
> * **Work email:** `avery@northstar-crm.example`
> * **Verification:** deliverable
>
> **Morgan Patel, Head of Sales at Fieldnote:** Fits the target role, but the returned address is **catch-all**. I would not treat it as verified.
>
> Each result includes its source and lookup date. I did **not** purchase personal contact details or send any emails.


# Compare AI Citation Visibility Against Competitors
Source: https://monid.ai/docs/examples/seo-visibility/ai-citations

Use Monid to compare your brand's AI citation counts against competitors with matched scope and clear limitations.

Give your agent three domains and a country. It uses Monid to collect comparable citation counts, keep platforms separate, and return a snapshot with plain-language conclusions.

<Tip>
  **Example question:** How does my brand's AI citation visibility compare with two competitors?
</Tip>

## Try it yourself (give it to your agent)

```text Prompt theme={null}
Use Monid to compare AI citation visibility for my brand and two competitors.

Ask for the three domains, target country, platforms of interest, and any previous report I want to compare against. My budget is $2. Inspect the current tools and confirm what their metrics mean before paying.

Collect comparable citation counts using the same available scope and date settings. Keep citations separate from mentions, recommendations, and responses to individual prompts. If no compatible historical baseline exists, treat this as the first snapshot rather than claiming growth or decline.

Return a plain-language summary and a domain-by-platform comparison table, followed by three useful next questions to investigate. Include source, settings, date, limitations, and actual spend. Do not claim the data reproduces live consumer chatbot answers or supplies individual cited URLs unless the endpoint actually returns them.
```

## Potential tools

* [**Ahrefs**](https://monid.ai/tools/ahrefs): `/site-explorer/ai-responses-count` returns available platform-level citation counts for a target.

The agent compares compatible results and explains the limitations. This endpoint is **not** an individual-answer or cited-page export.

## Example output

<Note>Names, counts, and details below are fictional. Real responses include actual sources, costs, and generated files.</Note>

> **Your brand trails Competitor A** in the measured citation dataset, but **leads Competitor B**.
>
> For one measured platform, using the same scope and date, the returned counts were:
>
> * **Your domain:** 120
> * **Competitor A:** 280
> * **Competitor B:** 75
>
> The comparison keeps each platform separate rather than adding them into a cross-platform total.
>
> This is your **first snapshot**, so I cannot say whether visibility improved or declined. These counts also do **not** establish which brand an individual chatbot will recommend.
>
> Next, I would investigate which content Competitor A publishes, whether important product pages are easy to access, and which topics deserve a separate citation-source analysis.


# Find Content Opportunities for Your Store
Source: https://monid.ai/docs/examples/seo-visibility/content-opportunities

Use Monid to recommend five prioritized content improvements grounded in customer questions and keyword evidence.

Give your agent your store URL, competitors, and audience. It uses Monid to find recurring customer questions, inspect competing pages, and return prioritized editorial recommendations.

<Tip>
  **Example question:** Which five pages or FAQs should a skincare store prioritize for US search traffic?
</Tip>

## Try it yourself (give it to your agent)

```text Prompt theme={null}
Use Monid to recommend five content improvements for a skincare ecommerce store targeting English-speaking customers in the US.

Ask for the store URL, main products, target customer, up to two competitors, and any existing articles or Search Console findings I can share. My budget is $3. Inspect prices and limit paid keyword checks to a small shortlist.

Find recurring customer questions in relevant public discussions, inspect competing pages, and use available keyword data to evaluate demand and intent. Recommend a new page, an FAQ addition, an update to an existing page, or no action for each topic. Avoid unsupported medical claims and do not treat keyword volume as a traffic guarantee.

Return five prioritized recommendations with supporting sources, the customer question, search intent, proposed title, outline, and first-hand product evidence needed. Include rejected topics and actual spend. Do not publish changes.
```

## Potential tools

* [**Ahrefs**](https://monid.ai/tools/ahrefs): `/site-explorer/top-pages` and `/keywords-explorer/overview` provide competing-page and keyword information.
* [**Reddit**](https://monid.ai/tools/reddit): Apify's `/practicaltools/apify-reddit-api` surfaces customer language.
* [**TinyFish**](https://monid.ai/tools/tinyfish): retrieves relevant pages.

The agent turns those inputs into editorial decisions.

## Example output

<Note>Names, counts, and details below are fictional. Real responses include actual sources, costs, and generated files.</Note>

> **Start with a *"How to choose your first skincare routine"* guide.** The reviewed discussions repeatedly ask about product order and avoiding unnecessary steps. Use your actual product instructions and have health-related statements reviewed appropriately.
>
> **Add a refill FAQ to the product pages.** Questions about replacing pumps, cleaning containers, and subscription timing are better answered near the purchase decision than in separate articles.
>
> **Update the moisturizer comparison page.** Explain texture, ingredients, intended use, and price with consistent comparison criteria.
>
> I would **skip** a generic *"best skincare ingredients"* article for now: it is broad, difficult to differentiate, and would require stronger expert evidence.
>
> The full recommendation includes **5 briefs** and the supporting research.


# How It Works
Source: https://monid.ai/docs/guide/how-it-works

How Monid works, and how you (or your agent) pay for what you use.

Monid is a unified gateway to hundreds of data endpoints across the web — for both humans and AI agents.

## Why Monid

<CardGroup>
  <Card title="Built for AI agents" icon="robot">
    The `discover` → `inspect` → `run` flow lets agents **find the best tool at runtime** and use it on demand — no need to pre-load every possible endpoint into context. Keep your prompts small and your agents fast.
  </Card>

  <Card title="One interface, one bill" icon="plug">
    A single unified API and a single wallet across every provider. No juggling keys, quotas, or contracts — ideal for developers and agent builders shipping fast.
  </Card>
</CardGroup>

## The Flow

<Steps>
  <Step title="Discover">
    Search endpoints in natural language (e.g. *"twitter posts"*, *"amazon reviews"*).
  </Step>

  <Step title="Inspect">
    View the input schema, output shape, and price for any endpoint.
  </Step>

  <Step title="Run">
    Execute the endpoint with your inputs and get results back.
  </Step>
</Steps>

Use it via [MCP](/docs/guide/quickstart-mcp), [Skill](/docs/guide/quickstart-skill), [CLI](/docs/guide/quickstart-cli), or [HTTP API](/docs/guide/quickstart-api).

## Pricing

Pay-as-you-go from a prepaid wallet. No subscriptions, no contracts.

* **Per-call** — flat fee per execution (e.g. `$0.003 / call`)
* **Per-result** — fee per item returned, with an optional base fee (e.g. `$0.002 + $0.001 / result`)

Prices are shown in `discover`, `inspect`, and `run` responses. See [Pricing](/docs/guide/pricing) for details.

## Next Steps

<CardGroup>
  <Card title="Set up an AI Agent" icon="robot" href="/docs/guide/quickstart-skill">
    Connect via MCP or install the Skill.
  </Card>

  <Card title="Set up as a Human" icon="terminal" href="/docs/guide/quickstart-cli">
    Use the CLI or call the API directly.
  </Card>
</CardGroup>


# Pay with x402
Source: https://monid.ai/docs/guide/pay-with-x402

Pay per run with a crypto wallet (USDC) using the x402 protocol instead of a prepaid Monid workspace balance.

[x402](https://docs.x402.org) lets you **pay per run with a crypto wallet (USDC)** instead of a prepaid Monid workspace balance. Your client signs an on-chain USDC payment in response to an HTTP `402 Payment Required`, and Monid settles it via a facilitator.

No workspace, no budget, no top-ups — payment is collected on-chain, per run.

<Note>
  x402 covers **execution and retrieval only**. Discovery and inspection still require a normal Monid API key — see [What the API key is still for](#what-the-api-key-is-still-for).
</Note>

## Prerequisites

* An [x402-compatible client](https://docs.x402.org/getting-started/quickstart-for-buyers) (e.g. `@x402/fetch`).
* A wallet funded with **USDC** and **native gas** on your chosen network (see below).

## Supported networks

Monid advertises every supported network in its 402 `accepts` array. Your client picks by matching the network it wants — don't blindly take `accepts[0]`.

| Network       | CAIP-2        | USDC contract                                | Gas token |
| ------------- | ------------- | -------------------------------------------- | --------- |
| Base mainnet  | `eip155:8453` | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` | ETH       |
| Monad mainnet | `eip155:143`  | `0x754704Bc059F8C67012fEd69BC8A327a5aafb603` | MON       |

<Info>
  **Minimum price:** `$0.01`. Monid raises the advertised price to this floor if the run's quote is lower.

  **Metered endpoints** (time-billed) are not available on x402 — x402 is a single fixed upfront payment.
</Info>

## Execute a run

Instead of running with the CLI:

```bash theme={null}
monid run -p <provider> -e <endpoint> -i '<input-json>'
```

Use an x402-compatible client to `POST` to `https://x402.monid.ai/v1/run`:

```bash theme={null}
# with x402-curl or any x402-aware client
x402-curl -X POST https://x402.monid.ai/v1/run \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "pdl",
    "endpoint": "person/enrich",
    "input": {}
  }'
```

The client handles the payment handshake for you: it receives the `402`, signs a USDC authorization, retries the request, and returns the run body once the payment is settled and the run completes.

`input` may carry `{ body, queryParams, pathParams }` — the same shape as the standard `/v1/run` endpoint.

### Response

* **`200`** — run completed. Body includes `runId`, `provider`, `endpoint`, `status`, `output`, `providerResponse`, `price`, `billing`, `billedUnits`, and `hints` (the poll URL is inside `hints`, not a top-level field). The HTTP status mirrors the provider's own status.
* **`408`** — `TIMED_OUT`. Zero-billed.
* **`400`** — invalid input, or an unsupported (metered) endpoint.

<Tip>
  Save the `runId` and poll URL from every successful run-creation response (`200` or `202`) — you'll need them to retrieve results later. Async `202` responses carry a top-level `pollUrl`; synchronous `200` responses carry it inside `hints`.
</Tip>

## Retrieve a run

Instead of getting a run with the CLI:

```bash theme={null}
monid runs get <runId>
```

Use an x402-compatible client to `GET` the `pollUrl` returned by the pay response:

```bash theme={null}
x402-curl https://x402.monid.ai/v1/runs/<runId>
```

This route requires **no payment** — just a Sign-In-With-X (SIWX) signature from the same wallet that paid for the run. Your x402 client handles the SIWX challenge automatically.

### Response

* **`200`** — run status and full body (`output`, `providerResponse`, `price`, `cost`, timestamps).
* **`401`** — signature invalid.
* **`403`** — you are not the wallet that paid for this run.
* **`404`** — run not found.

## List runs

**x402 does not support listing runs.** Access control is per-run wallet ownership, and there's no workspace to scope a list to. Retain each `runId` / `pollUrl` from your pay responses to retrieve them later.

If you need to list runs, use the workspace-scoped [`GET /v1/runs`](/docs/api/runs/list) with an API key.

## What the API key is still for

Even as an x402 user, you need a Monid API key for discovery, inspection, and listing runs.

| Capability         | Endpoint                            | Auth    | Payment       |
| ------------------ | ----------------------------------- | ------- | ------------- |
| Discover providers | `POST api.monid.ai/v1/discover`     | API key | none          |
| Inspect endpoints  | `POST api.monid.ai/v1/inspect`      | API key | none          |
| Execute a run      | `POST x402.monid.ai/v1/run`         | wallet  | USDC on-chain |
| Retrieve a run     | `GET  x402.monid.ai/v1/runs/:runId` | wallet  | none          |
| List runs          | `GET  api.monid.ai/v1/runs`         | API key | n/a           |

Typical loop: **discover / inspect** with your API key → **pay and run** with x402 → **retrieve** with x402.

## Next steps

* [Discover endpoints](/docs/api/discover) with your API key
* [Inspect an endpoint](/docs/api/inspect) before you pay
* [API Reference](/docs/api/overview) for the full `/v1/*` surface


# Set Up with API
Source: https://monid.ai/docs/guide/quickstart-api

Call the Monid HTTP API directly with your own code.

Call the Monid HTTP API directly from any language or runtime.

## 1. Get an API Key

Go to [Monid Dashboard](https://app.monid.ai) to create an account if you don't have one. Then go to [API key management page](https://app.monid.ai/access/api-keys) to create an API key.

**Copy the key — it is only shown once.**

## 2. Make Your First Request

All `/v1/*` endpoints require a Bearer token and JSON bodies.

```bash theme={null}
curl -X POST https://api.monid.ai/v1/discover \
  -H "Authorization: Bearer monid_live_..." \
  -H "Content-Type: application/json" \
  -d '{"query": "twitter posts"}'
```

## 3. Discover → Inspect → Run

```bash theme={null}
# Search for endpoints
curl -X POST https://api.monid.ai/v1/discover \
  -H "Authorization: Bearer monid_live_..." \
  -H "Content-Type: application/json" \
  -d '{"query":"twitter posts"}'

# Inspect an endpoint
curl -X POST https://api.monid.ai/v1/inspect \
  -H "Authorization: Bearer monid_live_..." \
  -H "Content-Type: application/json" \
  -d '{"provider":"apify","endpoint":"/apidojo/tweet-scraper"}'

# Run the endpoint
curl -X POST https://api.monid.ai/v1/run \
  -H "Authorization: Bearer monid_live_..." \
  -H "Content-Type: application/json" \
  -d '{"provider":"apify","endpoint":"/apidojo/tweet-scraper","input":{"searchTerms":["AI"],"maxItems":10}}'
```

## Next Steps

See the [API Reference](/docs/api/overview) for the full endpoint documentation.

<Note>
  Prefer paying per run with a crypto wallet (USDC) instead of a prepaid balance? See [Pay with x402](/docs/guide/pay-with-x402).
</Note>


# Set Up with Claude Tag
Source: https://monid.ai/docs/guide/quickstart-claude-tag

Connect Monid to Claude as a custom tool via a Claude Tag access bundle.

## Prerequisites

* A Claude organization with permission to manage Claude Tag settings.
* A Monid API key. You can create one on your [Monid Dashboard](https://app.monid.ai/access/api-keys).

## Steps

1. In your Claude organization settings, open **Claude Tag** settings.
2. Under **Claude Tag's Access**, select **All apps**.
3. Click the **+** to create a new access bundle and name it `Monid Access Bundle`.
4. Click **Connect** next to **Custom tool**.
5. Set **Name** to `Monid` and **Allowed websites** to `api.monid.ai` and `sfs.monid.ai`.
6. Get or create an API key at [Monid Dashboard](https://app.monid.ai/access/api-keys) and copy it.
7. Under **Custom headers**, add a header with **Name** `Authorization`, **Prefix** `Bearer`, and **Value** set to your Monid API key.
8. Click **Connect**.

Claude can now discover and run Monid endpoints through your access bundle.


# Set Up with CLI
Source: https://monid.ai/docs/guide/quickstart-cli

Install the Monid CLI and start querying data from the command line.

Install the Monid CLI and start querying data from the command line.

## 1. Install the CLI

```bash theme={null}
npm install -g @monid-ai/cli
```

Verify the installation:

```bash theme={null}
monid --version
```

## 2. Get an API Key

Go to [Monid Dashboard](https://app.monid.ai) to create an account if you don't have one. Then go to [API key management page](https://app.monid.ai/access/api-keys) to create an API key.

**Copy the key -- it is only shown once.**

## 3. Add the Key to the CLI

```bash theme={null}
monid keys add --label main --key <your-api-key>
```

Then activate the newly added API key:

```bash theme={null}
monid keys activate --label main
```

## 4. Example Usage

```bash theme={null}
# Search for data endpoints
monid discover -q "twitter posts"

# Inspect an endpoint to see its input schema and pricing
monid inspect -p apify -e /apidojo/tweet-scraper

# Run the endpoint
monid run -p apify -e /apidojo/tweet-scraper \
  -i '{"searchTerms":["AI"],"maxItems":10}'

# Get the results (use the run ID from the previous command)
monid runs get -r <run-id> -w
```

## Next Steps

See the [CLI Reference](/docs/cli/overview) for the full command documentation.

<Note>
  Prefer paying per run with a crypto wallet (USDC) instead of a prepaid balance? See [Pay with x402](/docs/guide/pay-with-x402).
</Note>


# Set Up with MCP
Source: https://monid.ai/docs/guide/quickstart-mcp

Connect your AI client to Monid via MCP (Streamable HTTP).

Connect your AI client to Monid via MCP (Streamable HTTP). No CLI installation needed.

## 1. Setup

<Tabs>
  <Tab title="Claude.ai (web)">
    1. Go to **Settings > Connectors** and select **Add custom connector**
    2. Enter Name `Monid` and MCP server URL `https://mcp.monid.ai/v1`, then click **Add**
    3. Click **Connect** and complete the authorization
  </Tab>

  <Tab title="Claude Code">
    1. In your terminal, run:
       ```bash theme={null}
       claude mcp add --transport http monid https://mcp.monid.ai/v1
       ```
    2. Open Claude Code and type `/mcp`, then select `monid`
    3. Select **Authenticate** and complete the authorization
  </Tab>

  <Tab title="Codex">
    1. In your terminal, run:
       ```bash theme={null}
       codex mcp add monid --url https://mcp.monid.ai/v1
       ```
    2. Your browser will be automatically opened for OAuth.
    3. Click allow to complete the authorization
  </Tab>

  <Tab title="OpenCode">
    1. Copy the following to your `opencode.json` config:
       ```json theme={null}
       {
         "mcp": {
           "monid": {
             "type": "remote",
             "url": "https://mcp.monid.ai/v1",
             "enabled": true
           }
         }
       }
       ```
    2. Run `opencode mcp auth monid` in your terminal and complete the authorization
  </Tab>

  <Tab title="Chatgpt">
    1. Hover over your personal account and open **Settings**.
    2. Go to **Plugins** → **Developer Mode** and enable **Developer Mode**.
    3. Return to the main page and click **Plugins** in the upper-left corner.
    4. Click the **+** icon next to the search bar to create a new plugin.
    5. Enter the following configuration:<br />**Plugin Name:** `monid`<br />**Connection URL:** `https://mcp.monid.ai/v1`
    6. Click **create** and **connect** to complete setup.
  </Tab>
</Tabs>

<Tip>
  Using a different agent? Find setup instructions for more MCP clients in the [Monid Dashboard](https://app.monid.ai).
</Tip>

## 2. Authentication

When prompted, log in with your Monid account (or sign up) and authorize the connection.

## 3. Start Using

Once connected, your agent has tools to discover, inspect, and run hundreds of data endpoints automatically. Try one of these prompts:

<AccordionGroup>
  <Accordion title="Find my public profile">
    > Find my public profile using Monid. Ask me for my name and current company if you don't know, then pull my work history, education, and public profiles.
  </Accordion>

  <Accordion title="Competitor research report">
    > Do a competitor research report using Monid. Ask me what product or company to research, then find its competitors and compare their pricing, features, market positioning, and recent social media buzz.
  </Accordion>

  <Accordion title="Find GTM leads">
    > Find GTM leads using Monid. Ask me about my target market and ideal customer profile, then search for matching contacts with details and find their LinkedIn, X/Twitter, emails, or other social media.
  </Accordion>

  <Accordion title="Analyze customer sentiment">
    > Analyze customer sentiment using Monid. Ask me for a product, then pull recent reviews from Amazon and social media, and summarize what people love vs complain about.
  </Accordion>
</AccordionGroup>

<Note>
  Prefer paying per run with a crypto wallet (USDC) instead of a prepaid balance? See [Pay with x402](/docs/guide/pay-with-x402).
</Note>


# Set Up with Skill
Source: https://monid.ai/docs/guide/quickstart-skill

Give your AI agent the ability to discover and run data endpoints across the web.

Give your AI agent (Claude Code, Cursor, etc.) the ability to discover and run data endpoints across the web.

## 1. Install the Monid Skill

Copy the following to your agent:

```text theme={null}
set up https://monid.ai/SKILL.md
```

This gives your agent the knowledge to discover, inspect, and run data endpoints automatically.

## 2. Get an API Key

Go to [Monid Dashboard](https://app.monid.ai) to create an account if you don't have one. Then go to [API key management page](https://app.monid.ai/access/api-keys) to create an API key.

**Copy the key -- it is only shown once.** Send the key to your agent so it can configure itself.

## 3. Start Using

Once the skill is installed and the API key is provided, your agent knows how to discover, inspect, and run data endpoints. Try one of these prompts:

<AccordionGroup>
  <Accordion title="Find my public profile">
    > Find my public profile using Monid. Ask me for my name and current company if you don't know, then pull my work history, education, and public profiles.
  </Accordion>

  <Accordion title="Competitor research report">
    > Do a competitor research report using Monid. Ask me what product or company to research, then find its competitors and compare their pricing, features, market positioning, and recent social media buzz.
  </Accordion>

  <Accordion title="Find GTM leads">
    > Find GTM leads using Monid. Ask me about my target market and ideal customer profile, then search for matching contacts with details and find their LinkedIn, X/Twitter, emails, or other social media.
  </Accordion>

  <Accordion title="Analyze customer sentiment">
    > Analyze customer sentiment using Monid. Ask me for a product, then pull recent reviews from Amazon and social media, and summarize what people love vs complain about.
  </Accordion>
</AccordionGroup>

The agent will handle the rest — discovering the right endpoints, checking their input schemas, running them, and returning the results.

<Note>
  Prefer paying per run with a crypto wallet (USDC) instead of a prepaid balance? See [Pay with x402](/docs/guide/pay-with-x402).
</Note>


# Welcome
Source: https://monid.ai/docs/index



Monid gives you (or your agent) on-demand access to hundreds of data endpoints across the web. Pay only for what you use — no subscriptions, no contracts.

## Get started

<Card title="How It Works" icon="book-open" href="/docs/guide/how-it-works">
  The 30-second overview — discover, inspect, run, and pay only for what you use.
</Card>

### Setup for AI Agents

<CardGroup>
  <Card title="MCP" icon="plug" href="/docs/guide/quickstart-mcp">
    Connect Claude, Codex, or OpenCode to Monid via MCP.
  </Card>

  <Card title="Skill" icon="robot" href="/docs/guide/quickstart-skill">
    Install the Monid skill in Claude Code, Cursor, and other agents.
  </Card>
</CardGroup>

### Setup for Humans

<CardGroup>
  <Card title="CLI" icon="terminal" href="/docs/guide/quickstart-cli">
    Install the CLI and query data from your shell.
  </Card>

  <Card title="API" icon="code" href="/docs/guide/quickstart-api">
    Call the HTTP API directly from your code.
  </Card>
</CardGroup>

## References

<CardGroup>
  <Card title="API Reference" icon="code" href="/docs/api/overview">
    HTTP endpoints for discover, inspect, run, runs, and wallet.
  </Card>

  <Card title="CLI Reference" icon="square-terminal" href="/docs/cli/overview">
    All `monid` commands with flags, examples, and output.
  </Card>

  <Card title="Integrations" icon="puzzle-piece" href="/docs/integrations/overview">
    Embed Monid in your own product via OAuth, proxy, or master API key.
  </Card>
</CardGroup>

## Links

* [Monid homepage](https://monid.ai)
* [**<u>List of Tools</u>**](https://monid.ai/tools)


# Set Up Direct Access
Source: https://monid.ai/docs/integrations/direct/setup

Call Monid server-to-server with a single API key for internal, user-invisible workflows.

Use Monid as an internal building block. Your backend calls Monid with a single API key; end users never see Monid or need their own account.

## 1. Create an API Key

Create an account at [Monid dashboard](https://app.monid.ai), then generate an API key at the API key management page. Store it as a server-side secret.

<Note>
  With a Monid API key the workspace is bound to the key — no `x-workspace-id` header is needed. Only OAuth/JWT tokens without an org context need the header. List available workspaces with [`GET /v1/auth/workspaces`](/docs/api/auth/workspaces).
</Note>

## 2. Pick a Pattern

### Pattern A: Full Discover / Inspect / Run

Best when your product (or internal agent) needs to pick tools dynamically.

<CardGroup>
  <Card title="POST /v1/discover" icon="magnifying-glass" href="/docs/api/discover">
    Search for endpoints in natural language.
  </Card>

  <Card title="POST /v1/inspect" icon="circle-info" href="/docs/api/inspect">
    Get the input schema, output shape, and price.
  </Card>

  <Card title="POST /v1/run" icon="play" href="/docs/api/run">
    Execute an endpoint and get results.
  </Card>
</CardGroup>

### Pattern B: Curated Endpoints Only

Best when you want a simple, fixed interface with predictable pricing. Pre-select the endpoints you care about, wrap them behind your own function or API, and call `run` directly.

Browse available endpoints at [monid.ai/tools](https://monid.ai/tools) to find the ones you want to expose.

```ts theme={null}
// Example: an internal helper that only exposes one endpoint
async function runTool(input: Record<string, unknown>) {
  const res = await fetch("https://api.monid.ai/v1/run", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.MONID_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      provider: "<provider>",
      endpoint: "<endpoint>",
      input,
    }),
  });
  return res.json();
}
```

## 3. Billing

All usage bills to your single Monid wallet with one invoice and no per-user setup. Charge your users however you like.

## Next Steps

* [API Reference](/docs/api/overview) — full endpoint documentation
* [How It Works](/docs/guide/how-it-works) — discover / inspect / run overview


# When to Use Monid Directly
Source: https://monid.ai/docs/integrations/direct/when-to-use

Use Monid directly when it's an internal building block of your product, not something users see.

Use Monid directly when **your users never see Monid** — it's an internal building block powering features inside your product. You hold a single Monid account and call the API server-to-server.

## Use Direct Integration When

* Monid is a hidden implementation detail (data enrichment, background jobs, agentic tools).
* You want the simplest possible integration — one API key, no OAuth flow.
* You bill users through your own system (subscription, per-feature, or free).
* You want a **unified billing surface**: one Monid invoice for all usage across your users.

## Two Patterns

<CardGroup>
  <Card title="Full discover / inspect / run" icon="compass">
    Let your backend (or an internal agent) pick endpoints dynamically at runtime. Best when the set of tools needed isn't known ahead of time.
  </Card>

  <Card title="Curated endpoints only" icon="list-check">
    Pre-select a handful of endpoints and call `run` on them directly. Best when you want a simple, fixed interface with predictable pricing.
  </Card>
</CardGroup>

## Skip Direct Integration When

* Your users should have their own Monid account and wallet → use [OAuth](/docs/integrations/oauth/when-to-use).
* You want to expose Monid tools to user-owned agents but with your own billing and allowlist → use [a Proxy](/docs/integrations/proxy/when-to-use).

## Examples

<AccordionGroup>
  <Accordion title="CRM that auto-enriches new leads">
    Whenever a new contact is created, the CRM's backend calls a curated Monid endpoint to pull LinkedIn + company data. Users never see "Monid" — they just see enriched contacts. The CRM pays Monid once a month and bills users on its own plan.
  </Accordion>

  <Accordion title="Agentic feature inside a SaaS product">
    A support tool has a "Research this ticket" button. Its internal agent uses Monid `discover` / `inspect` / `run` to find the right data source for each ticket. The user only sees the final summary.
  </Accordion>

  <Accordion title="Batch pipeline for analytics">
    A nightly job runs a fixed set of Monid scraping endpoints to refresh a dataset. No user interaction, no dynamic discovery — just direct `run` calls on known endpoints.
  </Accordion>
</AccordionGroup>

Ready to build? Continue to [Set Up Direct Access](/docs/integrations/direct).


# Set Up OAuth
Source: https://monid.ai/docs/integrations/oauth

Let your users sign in with Monid and act on their own workspace via OAuth 2.0.

Use OAuth 2.0 to let your users authorize your service to call the Monid API on their behalf. This is the right choice when your users manage their own Monid account and wallet.

## 1. Request OAuth Credentials

Email [support@monid.ai](mailto:support@monid.ai) to obtain:

* **Client ID**
* **Client Secret**
* **Whitelisted redirect URIs** (only required if you host your own callback)

If you don't have a callback URL, you can use Monid's hosted callback to display the authorization code for the user to copy and paste:

```text theme={null}
https://app.monid.ai/oauth/code/callback
```

## 2. OAuth Configuration

| Parameter              | Value                                                            |
| ---------------------- | ---------------------------------------------------------------- |
| **Issuer**             | `https://api.monid.ai`                                           |
| **Resource**           | `https://api.monid.ai/v1`                                        |
| **Redirect URI**       | Your own callback, or `https://app.monid.ai/oauth/code/callback` |
| **Discovery document** | `https://api.monid.ai/.well-known/openid-configuration`          |

Monid follows standard OAuth 2.0 / OpenID Connect. Point your OAuth client library at the discovery document above and it will auto-configure the authorization, token, userinfo, and introspection endpoints.

### Scopes

Request any subset of the following:

| Scope            | Purpose                                                                                                               |
| ---------------- | --------------------------------------------------------------------------------------------------------------------- |
| `openid`         | Required for OIDC. Enables ID tokens.                                                                                 |
| `profile`        | User's name and profile info.                                                                                         |
| `email`          | User's email address.                                                                                                 |
| `offline_access` | Return a refresh token so you can act while the user is offline.                                                      |
| `user:org:read`  | Read the user's organizations and workspaces (needed to call [`GET /v1/auth/workspaces`](/docs/api/auth/workspaces)). |

## 3. Authorization Flow

Monid uses the standard OAuth 2.0 **authorization code** flow (with PKCE recommended for public clients). Any OIDC-compliant client library will work — see [oauth.net](https://oauth.net/2/) or your library's docs for reference.

The flow at a glance:

<Steps>
  <Step title="Redirect the user to /oauth/authorize">
    Include `client_id`, `redirect_uri`, `scope`, `resource=https://api.monid.ai/v1`, and a `state` value.
  </Step>

  <Step title="Exchange the returned code at /oauth/token">
    You'll get back an `access_token` and (if `offline_access` was requested) a `refresh_token`.
  </Step>

  <Step title="Use the access token">
    Send `Authorization: Bearer <access_token>` on every Monid API call.
  </Step>
</Steps>

<Note>
  For the exact request/response shape of each endpoint, use the [OIDC discovery document](https://api.monid.ai/.well-known/openid-configuration) — it's the canonical source and always up to date.
</Note>

## 4. Select a Workspace

A Monid user can belong to multiple workspaces. If your access token carries an organization claim, the workspace is resolved from it automatically. When the token has no organization context, **include an `x-workspace-id` header** so Monid knows which workspace to operate against.

List the workspaces the user has access to — see [`GET /v1/auth/workspaces`](/docs/api/auth/workspaces):

```bash theme={null}
curl https://api.monid.ai/v1/auth/workspaces \
  -H "Authorization: Bearer <access-token>"
```

If your token lacks an organization context, pick a workspace and include its ID on every subsequent call:

```bash theme={null}
curl -X POST https://api.monid.ai/v1/discover \
  -H "Authorization: Bearer <access-token>" \
  -H "x-workspace-id: <workspace-id>" \
  -H "Content-Type: application/json" \
  -d '{"query":"twitter posts"}'
```

## 5. Call the API

Once you have an access token and a workspace ID, use the standard Monid API. See the [API Reference](/docs/api/overview) for all available endpoints.

<Note>
  Access tokens from OAuth act like scoped API keys. Never expose them to end‑user browsers or mobile clients — keep them on your server.
</Note>


# When to Use OAuth
Source: https://monid.ai/docs/integrations/oauth/when-to-use

Use OAuth when your users bring their own Monid account and act on their own workspace.

OAuth is the right choice when **your users own their Monid account** and you want them to authorize your product to act on their behalf.

## Use OAuth When

* Users already have (or want) their own Monid account and wallet.
* You don't want to handle billing, top‑ups, or account settings inside your product.
* You want each user to see their own usage and history at [Monid dashboard](https://app.monid.ai).
* Standard OAuth 2.0 / OIDC fits your existing auth stack.

## Skip OAuth When

* You want to charge users through your own billing system.
* You need to filter which Monid endpoints users can reach.
* Users shouldn't leave your product to authorize.

## Examples

<AccordionGroup>
  <Accordion title="A third-party AI agent platform">
    An agent-hosting platform lets users bring their own tools. Users click **Connect Monid**, authorize once, and every agent they build on the platform can call `discover` / `inspect` / `run` against their own workspace and wallet.
  </Accordion>

  <Accordion title="A no-code workflow builder">
    A Zapier-style product adds Monid as a connector. During setup, users authorize with OAuth. Each workflow step that calls Monid uses that user's access token — Monid charges the user, not the platform.
  </Accordion>
</AccordionGroup>

Ready to build? Continue to [Set Up OAuth](/docs/integrations/oauth).


# Integrations Overview
Source: https://monid.ai/docs/integrations/overview

Integrate Monid into your own product so your users can discover and run data endpoints.

Bring Monid's data endpoint marketplace into your own product. Pick the model that best fits your user experience and billing needs.

## Integration Methods

<CardGroup>
  <Card title="Use Monid Directly" icon="bolt" href="/docs/integrations/direct/when-to-use">
    Call Monid server-to-server as an internal building block. Users never see Monid.
  </Card>

  <Card title="OAuth" icon="key" href="/docs/integrations/oauth">
    Let your users sign in with Monid and act on their own workspace. Best when users manage their own Monid account.
  </Card>

  <Card title="Proxy" icon="shield" href="/docs/integrations/proxy">
    Run your own proxy in front of the Monid API. Control validation, billing, and endpoint access end‑to‑end.
  </Card>
</CardGroup>

## Need Help?

Email [support@monid.ai](mailto:support@monid.ai) to get an OAuth client or discuss custom setups.

<Note>
  Expecting high traffic? Reach out to [support@monid.ai](mailto:support@monid.ai) to discuss volume-based discounts.
</Note>


# Set Up Your Own Proxy
Source: https://monid.ai/docs/integrations/proxy

Run a proxy in front of the Monid API to control validation, billing, and endpoint access.

Run your own proxy in front of Monid, then point your users' agents (via [Skill](/docs/guide/quickstart-skill) or [MCP](/docs/guide/quickstart-mcp)) at your proxy. Your service sits in the middle and handles everything before the request reaches Monid.

## How It Works

<Steps>
  <Step title="Create your own proxy server">
    Stand up an HTTP server at a URL you control (e.g. `https://your-proxy.example.com`). It will accept the same request shapes as the Monid API.
  </Step>

  <Step title="Install the Monid Skill or CLI and point it at your proxy">
    Install the [Monid Skill](https://monid.ai/SKILL.md) and the [Monid CLI](/docs/guide/quickstart-cli), then set the environment variable to your proxy URL:

    ```bash theme={null}
    export MONID_API_BASE_URL=https://your-proxy.example.com
    ```

    All Monid CLI traffic will now hit your proxy instead of `https://api.monid.ai`.
  </Step>

  <Step title="Your proxy decides and forwards">
    Every `discover`, `inspect`, and `run` call arrives at your proxy. Inspect the request, apply your own auth / billing / allowlist, and forward approved requests to `https://api.monid.ai` using your own Monid credentials. Return the response to the caller.
  </Step>
</Steps>

## What Your Proxy Can Do

* **Validate incoming requests** — authenticate your own users, enforce rate limits, and check inputs.
* **Bill your own way** — charge in dollars, credits, or subscription tiers, with or without markup on Monid's per‑call and per‑result pricing.
* **Whitelist or blocklist endpoints** — restrict which Monid endpoints your users can reach.
* **Rewrite or enrich responses** — add your own metadata, cache results, or transform payloads.

## Environment Variable

Set the Monid client's base URL to your proxy:

```bash theme={null}
export MONID_API_BASE_URL=https://your-proxy.example.com
```

The [Skill](/docs/guide/quickstart-skill), [MCP](/docs/guide/quickstart-mcp), [CLI](/docs/guide/quickstart-cli), and API clients all respect this variable.

## Forwarding to Monid

Inside your proxy, forward approved requests to Monid using your own API key or an OAuth access token. With an API key the workspace is bound to the key; for OAuth tokens without an org context, include an `x-workspace-id` header — get available workspace IDs from [`GET /v1/auth/workspaces`](/docs/api/auth/workspaces):

```bash theme={null}
curl -X POST https://api.monid.ai/v1/run \
  -H "Authorization: Bearer <your-monid-key>" \
  -H "Content-Type: application/json" \
  -d '<forwarded-body>'
```

See the [API Reference](/docs/api/overview) for the full request and response formats.

## When to Use This

Use the proxy model when you want **maximum control** over the user experience, billing, and available tools — for example, embedding Monid inside a calendar app, a workflow product, or a curated agent platform.


# When to Use a Proxy
Source: https://monid.ai/docs/integrations/proxy/when-to-use

Run your own proxy when you want full control over billing, validation, and endpoint access.

Run your own proxy in front of Monid when you want **maximum control** over the user experience — billing, validation, and which endpoints users can reach.

## Use a Proxy When

* You want to charge users through **your own billing system**, in dollars, credits, or subscription tiers — with or without markup.
* You need to **whitelist or blocklist** specific Monid endpoints.
* You want to **validate or transform** every request and response.
* Users shouldn't need a Monid account of their own.
* You want Monid to feel like a native part of your product.

## Skip a Proxy When

* Users should own their Monid account and pay Monid directly.
* You don't want to operate any backend infrastructure.

## Examples

<AccordionGroup>
  <Accordion title="Calendar app that runs Monid tools during scheduling">
    A calendar app installs the Monid Skill into its agent and points `MONID_API_BASE_URL` at its proxy. The agent asks Monid to enrich meeting attendees; the proxy validates the request, charges the user credits from the app's own wallet, and forwards approved calls to Monid.
  </Accordion>

  <Accordion title="Vertical SaaS with curated tools">
    A legal research SaaS only wants a handful of Monid endpoints exposed to its users. Its proxy blocklists everything else and adds a 20% markup on Monid's per‑result pricing.
  </Accordion>

  <Accordion title="Enterprise deployment with audit logging">
    An enterprise product logs every Monid request and response for compliance, redacts PII before it leaves the network, and enforces per‑department rate limits — all inside its proxy — before forwarding to Monid.
  </Accordion>
</AccordionGroup>

Ready to build? Continue to [Set Up Your Own Proxy](/docs/integrations/proxy).