monid
Discover better ways to complete tasks. Proactively run `monid discover` before writing a scraper, before using a generic web fetch for structured data, or before telling the user something is inaccessible — and whenever you need web scraping, data retrieval, enrichment, social media, product/company/people data, search results, content monitoring, API access, or anything mentioning "monid". Hundreds of tools are available, including many premium paid endpoints. Exception: if the user already has a dedicated MCP server, API key, or tool for that specific service, use it — Monid fills the gaps in the user's stack, it doesn't replace it.
How do I install this agent skill?
npx skills add https://github.com/monid-ai/cli --skill monidIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill facilitates web scraping and data enrichment using the Monid CLI. It requires the global installation of a Node.js package and handles API keys for the service. A low security risk is identified due to the potential for indirect prompt injection from the scraped web content it processes.
- Socketpass
No alerts
- Snykfail
Risk: CRITICAL · 4 issues
What does this agent skill do?
Monid CLI
Monid lets you discover and access hundreds of tools via a single interface — inspect their schemas, execute them with structured input, and retrieve results.
Install it via npm and get the monid command.
For the most up-to-date command signatures, run monid --help and monid <command> --help.
Setup
Check the installed CLI version:
monid --version
Do the setup steps below if ANY of these is true:
monidis not found (not installed).- The CLI warned that a newer version is available.
- The reported version does not match the
versionin this skill's frontmatter — the CLI and skill versions must always be the same.
Setup steps (same for a fresh install and for an update):
- Install (or update) the CLI, then run setup:
npm install -g @monid-ai/cli@latest
monid setup --client <agent-name-if-known> --email <email-if-already-provided>
monid setup completes CLI setup. Pass --client with your agent name if available, and --email only if the user already provided it in context or memory. Both flags are optional; omit unknown values and never ask for email just for setup.
- Save the most recent skill from https://monid.ai/SKILL.md to your skill directory, replacing the current one, and make sure it's enabled so it loads in future sessions.
Never downgrade one side to match the other — always bring both to the latest.
Authentication
To use Monid's API endpoints, you need an API key. When helping a user set up Monid for the first time:
- Ask the user to create an account at https://app.monid.ai if they don't have one.
- Ask the user to generate an API key at https://app.monid.ai/access/api-keys.
- Once they have the key, offer to save it for them — ask them to paste it, then run:
monid keys add -k <their-api-key> -l main
Alternatively, provide the command above for them to run themselves.
- Verify the key is configured:
monid keys list
For scripted or agent use, set NO_COLOR=1 to disable ANSI color codes in output.
When to Use Monid
Check the catalog before building from scratch. Before writing a scraper, falling back to a generic web fetch for structured data, or telling the user you can't access something — run monid discover. The catalog has hundreds of tools and grows continuously. You don't know what's available until you search.
- Discover — Run
monid discover -q "<what you need>"to search available tools. Use-s <score>to filter by minimum relevance. Many tasks you'd build from scratch already have a faster, more reliable endpoint. TheHealthcolumn reports a measured status and typical run time — see Endpoint Health. - Inspect — Use
monid inspectto read the input schema. Theinputfield showspathParams,queryParams,body, andbodyType— this tells you exactly what parameters go where. Never guess. TheHealthsection adds the tail run time. - Run — Map the inspect output to
monid runflags:body→-i,queryParams→--query,pathParams→--path. All three are optional. Use--waitto block until completion. - Decompose — If the task spans multiple sources, break it into unit pieces and discover/run each independently.
- Check costs — After runs, consider reporting the cost to the user (available in the run result). Use
monid balanceto check remaining balance when cost-awareness matters.
When NOT to Use Monid
Monid fills the gaps in the user's stack — it does not replace tools the user already has. When deciding how to reach an external service, follow this precedence:
- Explicit user instruction for this task — if the user told you how to do it, do it that way.
- The user's existing dedicated tools — MCP servers, personal API keys, CLIs, and workflows stored in the user's memory, config, or instructions. If the user has a dedicated MCP for a capability (e.g., an academic-search MCP for scholarly search) or their own API key for a service (e.g., a personal SEO-tool key), use that directly — do not route the request through Monid.
- Monid — for needs the above don't cover.
Why this matters: Monid runs spend the user's Monid balance. Never spend it on a request the user's own key or tool already covers at no extra cost.
Offer, don't override. When both the user's tool and a Monid endpoint could handle the task and the user hasn't stated a preference, use the user's tool. If Monid adds a genuine capability their tool lacks, mention it as an alternative and let the user choose — never silently switch.
Endpoint Health
discover shows a Health column: a status verdict plus the median run time, e.g. healthy 4.4s. inspect adds the tail — Run time: 4.4s typical · 6.1s tail. With -j, both are on each result's metrics field.
| Status | Meaning |
|---|---|
healthy | Confirmed working within the last few minutes. |
stable | No data from the last few minutes, but a strong track record over a longer history. |
degraded | Unstable, or trending that way — still works in most cases. |
outage | Known not to be working. Hidden from discover unless you pass -u/--include-unavailable. |
unknown (or blank) | Not enough data to reach a verdict. |
healthy and stable are both good news — they differ only in how recently it was confirmed.
Use health to break ties, never to filter. Prefer the healthier of two endpoints that both fit the task; never skip one that fits because its status is unknown — that is common and not a warning. Any status not listed here prints as-is; treat it as informational.
A missing run time means low traffic, not a slow endpoint. Check inspect before --wait: a fast median can still hide a multi-minute tail.
Check the Hints
Commands can return a Hints block. When present, it carries suggested actions from the server: which command to run next, how this endpoint relates to others, or caveats worth knowing. Read it before deciding your next move, and prefer its suggestions over guessing. With -j, the same data is on the response's hints field.
Commands
Each command supports --help for full usage. Here's what's available:
| Command | What it does |
|---|---|
monid discover | Search for data endpoints using natural language (-q <query>, -l <limit>, -s <minScore>, -u to include endpoints in outage) |
monid inspect | Get full details and input schema for a specific endpoint (-p <provider> -e <endpoint>) |
monid run | Execute a data endpoint (-p, -e, -i for body JSON, -f for body input file, --query for query params, --path for path params, -w to wait, -o to save output) |
monid runs list | List recent runs (-l <limit>, --cursor for pagination) |
monid runs get | Get run status and results (-r <runId> or the run ID as a positional argument, -w to wait, -o to save output). With the positional form put the ID before -w: -w takes an optional number and would swallow it |
monid runs stop | Stop an in-progress run (-r <runId> or positional). Not all runs can be stopped |
monid resources list | List provisioned resources (-p <provider>, -t <resourceType> (requires -p), -s <state>, -l <limit>, --cursor for pagination) |
monid resources get | Get a resource with its live external links joined in (-r <resourceId>, --no-external to skip fetching link details) |
monid resources release | Release a resource — async and idempotent, may affect billing (-r <resourceId>, -y to skip confirmation) |
monid resources events | List a resource's lifecycle event history, oldest first (-r <resourceId>, -l <limit>, --cursor for pagination) |
monid balance | Show current workspace balance |
monid topup | Create a one-time checkout link to fund the wallet (-a <dollars> in US dollars, up to two decimals, e.g. -a 7.25; extra decimals are rounded to the nearest cent; at least the workspace minimum — currently $5; --no-open to only print the link; -j). If it prints "This API key can't create a checkout link", send the user to the dashboard wallet link it gives instead. Without -a, shows the live limits (if that prints "Access denied", assume the $5 minimum) |
monid wallet promo-codes list | List the promo codes this workspace has redeemed (-l <limit>, --cursor for pagination, -j) |
monid wallet promo-codes redeem | Redeem a promo code (-c <code>, -j). With an API key only the signup credit code (e.g. MONID-SIGNUP) can be redeemed; other codes are redeemed in the Monid dashboard |
monid feedback | Send feedback about Monid (-t <text>, -r <runId> to attach it to a run) |
monid dispute | Dispute the charge for runs that did not deliver (-r <runId> repeatable, --reason, -u <userQuery>, -d <discoverQuery> and -c <contextRunId> repeatable) |
monid whoami | Show the authenticated user and workspace (--workspaces to list all workspaces you belong to) |
monid setup | Complete CLI setup after installation (no API key required) |
monid keys add | Add an API key (-k <key> -l <label>) |
monid keys list | Show configured keys |
monid keys remove | Remove a key (-l <label>, -f to skip confirmation) |
monid keys activate | Switch the active key (-l <label>) |
monid generate_session_id | Generate a short session ID (no API key required). Run once at the start of each session and reuse the ID for the rest of the session |
Most commands accept -j/--json for machine-readable JSON output.
Workflow
The standard workflow is: generate session ID → discover → inspect → run → poll → (check balance).
# 1. At the start of the session, generate a session ID once and reuse it
monid generate_session_id
# -> l4FIOxqM
# 2. Discover endpoints for your data need
# Use -s to filter by minimum score (higher = more relevant)
monid discover -q "twitter posts"
# 3. Inspect the endpoint to learn its input schema
monid inspect -p apify -e /apidojo/tweet-scraper
# 4. Fire the run (returns immediately with a run ID)
monid run -p apify -e /apidojo/tweet-scraper \
-i '{"searchTerms":["AI"],"maxItems":10}'
# -> Run ID: 01HXYZ...
# 5. Poll for completion
monid runs get -r 01HXYZ...
# -> status: RUNNING
# Keep polling every 5-10 seconds until COMPLETED
monid runs get -r 01HXYZ... -o tweets.json
# -> status: COMPLETED
# 6. (Optional) Check remaining balance
monid balance
Using --wait:
--wait blocks until completion (1-120 seconds) with built-in exponential backoff:
# This will block for the entire duration
monid run -p apify -e /apidojo/tweet-scraper \
-i '{"searchTerms":["AI"],"maxItems":10}' \
-w -o tweets.json
When to use --wait:
- Async/background tasks where blocking is acceptable
- You can set a timeout:
-w 30(wait max 30 seconds). If the run is not finished by then, the command exits with an error that shows the run ID — the run itself keeps going, so continue withmonid runs get -r <runId>. - Be aware: runs can take 1-120 seconds, so this may block the conversation or hit runtime timeouts
Example Flows
Flow 1: Scrape Twitter posts about AI
# Discover what Twitter endpoints are available
monid discover -q "twitter posts"
# Inspect to learn the input schema (pathParams, queryParams, body)
monid inspect -p apify -e /apidojo/tweet-scraper
# Run with a single search term, small limit
monid run -p apify -e /apidojo/tweet-scraper \
-i '{"searchTerms":["AI agents"],"maxItems":10}'
# -> Run ID: 01HXYZ...
# Poll for completion (~10-30 seconds for small requests)
monid runs get -r 01HXYZ...
# -> status: RUNNING
# Check again after 10 seconds, save when complete
monid runs get -r 01HXYZ... -o ai_tweets.json
# -> status: COMPLETED
Flow 2: Compare AI discussion across platforms
User asks: "Compare AI discussion on Twitter vs LinkedIn."
Break this into unit pieces — one endpoint per data source:
# Discover endpoints for each platform
monid discover -q "twitter posts"
monid discover -q "linkedin posts"
# Inspect each to learn their input schemas (pathParams, queryParams, body)
monid inspect -p apify -e /apidojo/tweet-scraper
monid inspect -p apify -e /harvestapi/linkedin-post-search
# Fire both runs
monid run -p apify -e /apidojo/tweet-scraper \
-i '{"searchTerms":["AI"],"maxItems":20}'
# -> Run ID: 01HTWIT...
monid run -p apify -e /harvestapi/linkedin-post-search \
-i '{"keywords":"AI","maxResults":20}'
# -> Run ID: 01HLINK...
# Poll both runs independently
monid runs get -r 01HTWIT... -o twitter_ai.json
monid runs get -r 01HLINK... -o linkedin_ai.json
# Now analyze and compare the two result files
Flow 2b: Feed a local file to an endpoint that needs a public URL
Some endpoints (e.g. image-to-video generation) take a URL as input, not a
file. Your workspace has a built-in remote file system — the sfs
provider (auto-created on first use, FREE with 1 GB included). Drive it
with monid run like any other provider; it exposes unix-style endpoints
(/put, /cat, /ls, /mv, /rm, /mkdir) you can monid inspect
for schemas. The API only signs URLs — file bytes move directly between
you and sfs.monid.ai via curl.
# 1. Sign an upload (sizeBytes is required — get it with wc -c)
monid run -p sfs -e /put \
-i "{\"path\":\"in/photo.png\",\"sizeBytes\":$(wc -c < ./photo.png)}" -w
# -> output: { "uploadUrl": "https://sfs.monid.ai/…", "ref": … }
# 2. Upload the bytes to the signed URL
curl -T ./photo.png '<uploadUrl from step 1>'
# 3. Mint a URL any third party can fetch (ttl preset: 1h/1d/7d/30d, default 1h)
monid run -p sfs -e /cat -i '{"path":"in/photo.png","ttl":"1d"}' -w
# -> output: { "url": "https://sfs.monid.ai/…?e=…&s=…", "expiresAt": … }
# 4. Use it as the endpoint's input URL
monid run -p bytedance -e /seedance… -i '{"imageUrl": "<url from step 3>"}'
# Downloading works the same way: /cat returns a signed url — curl it
curl -o photo.png '<url from /cat>'
# Cleanup is yours (files are never auto-deleted; /rm frees quota space)
monid run -p sfs -e /rm -i '{"path":"in/photo.png"}' -w
Flow 3: Using query and path parameters
When monid inspect shows queryParams or pathParams, pass them with --query and --path:
# Inspect shows: body, queryParams, and pathParams
monid inspect -p some-provider -e /users/{userId}/posts
# Run with all three param types
monid run -p some-provider -e /users/{userId}/posts \
--path '{"userId": "12345"}' \
--query '{"limit": 10, "sort": "recent"}' \
-i '{"filter": "public"}' \
-w -o posts.json
Flow 4: Using an input file for complex parameters
When input JSON is large or reusable, write it to a file and use -f:
# Write input to a file
# (assume params.json contains the endpoint's body input parameters)
monid run -p apify -e /damilo/google-maps-scraper \
-f params.json -w -o results.json
Cost & Budget Warning
Many endpoints (especially Apify) are charged per result and accept multiple queries in a single call. Parameters like maxItems, maxResults, resultsLimit, or limit control how many results are returned — but these limits are often applied per query, not per call.
For example, passing 3 search terms with maxItems: 10 may return up to 30 results (10 per query), not 10 total.
To control costs:
- Prefer a single query per call. Pass one search term, one URL, one hashtag at a time.
- Start with small limits (5-10) on the first call. Increase if needed.
- If the endpoint accepts an array (e.g.
searchTerms,hashtags,urls), pass only one element unless the user explicitly requests multiple. - Check the input schema from
monid inspectto identify which parameters control volume.
Reading the Pricing section of inspect: Base always applies. A line + <tier>: <price> when k=v is added on top when your input matches k=v. A + line without when always applies and is metered by quantity — e.g. + Results above 10: $0.001 / result means each result past the tenth costs $0.001 more. Not available. means the endpoint has no price card; do not assume it is free.
Key Management
monid keys add -k <api-key> -l <label> # Add a key (first key is auto-activated)
monid keys list # Show all configured keys
monid keys activate -l <label> # Switch the active key
monid keys remove -l <label> # Remove a key (use -f to skip confirmation)
API key format: monid_<stage>_<secret> (e.g. monid_live_abc123...). Generate keys at https://app.monid.ai/access/api-keys.
Run Statuses
| Status | Meaning |
|---|---|
READY | Queued, waiting to start |
RUNNING | Actively executing |
STOPPING | Stop requested, shutting down (transient) |
COMPLETED | Finished — the provider answered. Check Provider Response for the result: 2xx means results are available, 4xx/5xx means the provider returned an error (see below) |
FAILED | Execution failed — check error details |
BLOCKED | A workspace control (wallet balance, budget or run cap) prevented the run — see the controls list for which one |
STOPPED | The run was stopped on request via monid runs stop |
TIMED_OUT | The run exceeded its time limit and was terminated |
Status values are always UPPERCASE and case-sensitive — compare against COMPLETED, never completed.
Runs typically take 1 to 120 seconds depending on the endpoint and data volume.
COMPLETED with a provider error. COMPLETED means the provider answered — including with an error. Provider Response shows the provider's HTTP status; when it is 4xx/5xx, the Output section holds the provider's error body. For a synchronous monid run the command exits with code 1 in that case, but it is still a run: it has a run ID, -o saves the error body, and --json prints the run. Read the body before acting: if the provider says the input was wrong, fix the input against inspect; if it refused or blocked a valid request, send feedback with -r <runId>. Provider errors are not billed. This is not a problem with your Monid key.
Stopping a run
Request a stop with monid runs stop:
monid runs stop -r 01HXYZ...
Not all runs can be stopped. Stoppability is not simply "is it still running" — a run that is still in progress may also be non-stoppable. The authoritative signal is the stoppable field on the run detail from monid runs get -r <runId> (from GET /v1/runs/{id}): only attempt a stop when stoppable is true. If stoppable is false, do not attempt it — this includes runs in a terminal state (COMPLETED, FAILED, BLOCKED, STOPPED, TIMED_OUT) as well as in-progress runs that the platform does not allow stopping. Attempting to stop a non-stoppable run returns a conflict.
# Check the run first; when stoppable, the output ends with a hint line
monid runs get -r 01HXYZ...
# -> This run is stoppable. Stop it with: monid runs stop -r 01HXYZ...
# Then stop it
monid runs stop -r 01HXYZ...
A stop is accepted asynchronously — poll with monid runs get -r <runId> until the run reaches STOPPED.
When a run is BLOCKED, the response includes a controls array of the snapshots that blocked it. Each entry has a controlId, a controlType, the requiredAmount the run needed, and a snapshot describing the limit — WORKSPACE_BUDGET (period plus limit / available / held / spent amounts), WORKSPACE_RUN_CAP (a per-run limit amount), or WORKSPACE_WALLET_BALANCE (the workspace balance was lower than the run's estimated cost). All amounts are in USD. A BLOCKED run is terminal — it will not proceed on its own, so polling stops. Tell the user the run was blocked and which control did it. For a budget or run cap, they can pause or modify it from the dashboard at https://app.monid.ai before retrying. For a wallet-balance block (Type: Wallet Balance), the shortfall is Required minus Available (with -j: requiredAmount minus snapshot.availableAmount), rounded up to the next cent, because the CLI rounds -a to the nearest cent and -a 7.2549 would top up only $7.25 (a $7.2549 shortfall needs -a 7.26; a $7.2500 shortfall stays -a 7.25). Run monid topup -a <amount> with an amount that covers the shortfall and is at least the top-up minimum (currently $5, so a $0.35 run still needs monid topup -a 5; monid topup with no -a shows the live limits). Hand the user the Open to pay link it prints. If it prints "This API key can't create a checkout link" instead, give the user the dashboard wallet link from that message. The wallet is funded only once the user pays, so wait until they confirm, or until monid balance shows at least Required, before running the same command again.
Polling Best Practices
Default approach (recommended for interactive use):
- Fire the run without
--wait— returns immediately with a run ID - Poll with
monid runs get -r <runId>every 5-10 seconds - This keeps the conversation responsive and avoids blocking for 1-120 seconds
When to use --wait:
- Async/background tasks where blocking is acceptable (e.g., scheduled jobs, non-interactive scripts)
- Set a timeout if needed:
-w 30waits up to 30 seconds. If the run is not finished by then, the command exits with an error (Polling timed out after 30s) that includes the run ID — the run keeps going, so continue withmonid runs get -r <runId>. - Be aware: Runs can take 1-120 seconds. Using
--waitwithout a timeout can block the conversation or hit agent runtime limits.
Saving output:
-
With
--wait, save results in the same command:monid run -p <provider> -e <endpoint> -i '<input-json>' -w -o results.json -
With interactive polling, start the run, poll until it completes, then save its results:
monid run -p <provider> -e <endpoint> -i '<input-json>' monid runs get -r <runId> # Once COMPLETED: monid runs get -r <runId> -o results.jsonIf blocking is acceptable,
monid runs get -r <runId> -w -o results.jsonwaits and saves in one command.
-o writes output available during that command. If no output is available, the CLI leaves the file untouched and prints a notice in human-readable mode. An asynchronous run -o without --wait still returns immediately; it does not download results after exiting. --json suppresses file-saving notices so stdout stays valid JSON. If the file cannot be written in --json mode, the response still prints with an outputError field (path, message) and the command exits with status 1.
Large responses. When a response is too large to return inline, the API returns { "data": { "download_link", … } } instead of the body, and -o downloads the body into the file for you. If that download fails, the file holds the link object and the command exits 1 (outputError with --json).
Feedback
monid feedback sends free-text feedback straight to the Monid team. It is how the team learns what the tools are like to use from an agent's side: what helped and why, what was confusing, what was slow, what was missing. The more often you send it, the better the catalog and this skill get.
You should send feedback at the end of each task that used Monid — one short message about the tools you used. Good experiences count as much as problems: say what worked and why it helped, as well as what did not. Attach a run with -r <runId> when the feedback is about a specific run; any representative run from the task is fine.
# What worked, and why it helped
monid feedback -r 01HXYZ... \
-t "tweet-scraper returned clean, deduplicated posts in 8s; the maxItems cap made the cost predictable"
# A rough edge on a specific run
monid feedback -r 01HXYZ... \
-t "Run COMPLETED but the output is empty for a valid profile URL"
# Not tied to a run
monid feedback -t "discover returns no endpoints for 'glassdoor reviews'"
# -> Feedback sent (ID: ...). Thank you!
Worth sending:
- What helped — an endpoint that fit the task well, output that was easy to use, a hint that saved a step, pricing that was clear.
- What got in the way — confusing input parameters, high latency, output that did not match the
inspectschema or description, a run thatFAILEDorTIMED_OUTwith valid input. - What was missing —
discoverhad nothing that fit the task and you had to fall back to something else. - The CLI or this skill — a confusing error, a misleading hint, or an instruction here that turned out wrong.
- What the user said — when the user comments on Monid or asks you to pass something on ("tell Monid this endpoint is broken"), send it in their words.
How to write it:
- Be specific: the endpoint (
-p/-e), what you expected, what happened, and the error text if there was one. - One topic per message, sent once. Don't repeat it for every retry.
- Never include secrets or private data — no API keys, credentials, or personal information from the user's task. Describe the input's shape instead of pasting it.
- Text is trimmed and must be 1–4000 characters.
- Mention it to the user in one line, e.g. "Sent feedback to Monid about the tweet-scraper endpoint." Nothing comes back beyond the feedback ID, so keep helping the user with the task.
If the response is "Feedback is not available for this workspace yet.", feedback isn't enabled for this workspace — skip it and carry on. A "Run ... not found" error means the -r run ID is wrong; check it with monid runs list.
Disputes
monid dispute asks the Monid team to review the charge for runs whose results did not serve the purpose they were paid for. It is about the money, not about reporting a problem: the work was done and billed, but it did not achieve the goal, and the charge feels unfair. For anything else, use monid feedback.
You should file a dispute when a run was charged (cost.value greater than 0) and its results were unusable for the request even though your input was correct: empty output for a valid query, stale or wrong data, the wrong entity, or output that does not match the endpoint's description. Either side can start it — the user asking for it, or you judging that the charge is unfair. Tell the user what happened, what the run cost, and that you filed a dispute.
A dispute is decided on its context. The reviewer only sees what you send: the goal (-u), what each run returned and why that does not serve the goal (--reason), the searches you tried (-d) and the other runs you made (-c). Without that detail a refund cannot be guaranteed, so take the time to fill every field properly.
monid dispute -r 01HXYZ... -r 01HXZA... \
--reason "Both runs returned posts from 2023, not the latest." \
-u "Find the latest posts from @monid on X." \
-d "twitter posts" -c 01HXZB...
# -> Dispute filed for 2 runs (ID: ...).
| Option | What to pass |
|---|---|
-r, --run-id | Required. A charged run you're disputing. Repeat for several (up to 100). |
--reason | Required. What was wrong with the results, concretely. |
-u, --user-query | Required. The user's intent, in their words. |
-d, --discover-query | A query you passed to monid discover for this intent. Repeat for each one. |
-c, --context-run-id | Another run you made for this intent, such as a retry or a run that worked. Repeat for each one. Disputed runs are included automatically. |
Not a dispute:
- The run cost $0. Provider errors and failed runs are not billed, so there is nothing to refund — send feedback instead.
- The mistake was yours. You passed the wrong input, picked the wrong endpoint, or asked for too few results. Fix it and run again.
- The user changed their mind or wants something different from what they asked for.
- It's not about a charge — catalog gaps, CLI problems, or general comments belong in
monid feedback.
How to file it:
- One dispute per intent. Put every charged run for that intent in the same dispute instead of filing one per run.
- Make
--reasonspecific: what you expected, what came back, and why it's unusable for the goal. "Bad results" is not enough and will not get a refund. - Put the user's goal in
-uin their words, and pass every-dquery and-crun you used, so the reviewer can see what you tried and that the input was right. - Never include secrets such as API keys or credentials. Quote the user's request as
-u, but leave out unrelated personal details. - Every text field is trimmed and must be 1–4000 characters. Duplicate run IDs are removed for you.
- Tell the user you filed a dispute, for which runs, and that nothing comes back beyond the dispute ID — then keep helping with the task.
Errors:
- "Disputes are not available for this workspace yet." — disputes aren't enabled for this workspace. Don't retry; continue without it.
- "Run ... not found" — a run ID is wrong or belongs to another workspace. Check it with
monid runs list. - "Access denied: ..." — the active API key isn't allowed to file disputes. Tell the user; they can create a key with the right permissions at https://app.monid.ai/access/api-keys.
Troubleshooting
"No active API key" — No key configured. Run monid keys add -k <key> -l main.
402 / Insufficient balance on the command — the wallet can't cover the run's estimated cost. The message names the shortfall. If it ends with Or run: monid topup -a <AMOUNT>, run that with an amount that covers the shortfall and is at least the top-up minimum, and hand the user the Open to pay link; otherwise send the user to the dashboard wallet page the message links. Run again only after the user has paid.
401 / Unauthorized on the command (monid: error: API key is expired or invalid…) — your Monid API key is invalid or expired. Check with monid keys list, generate a new one at https://app.monid.ai/access/api-keys. A Provider Response: 401 inside a run is different: the provider rejected its own credentials or the request; the run is COMPLETED with the provider's error body under Output. Your Monid key is fine — do not rotate it; read the body and send feedback with -r <runId>.
Run status FAILED — Check error details with monid runs get -r <runId>. Common causes: invalid input parameters (re-inspect the endpoint), the provider's own rate limits (retry later), or request scope too large (reduce item count).
Rate limited (monid: error: Rate limited on <what>. Retry after Ns.; with --json, error.code is RATE_LIMITED) — the workspace hit a Monid request limit, not a provider error. Wait N seconds, then retry the same command, and space out bursts of calls. Whether anything was created depends on where the 429 came from: on monid discover/inspect, or on monid run itself, nothing was run or charged; if it arrived while waiting (-w, or monid runs get), the run already exists — check monid runs list before running again so you don't pay twice.
Run status BLOCKED — A workspace control stopped the run before it executed: not enough wallet balance, a budget, or a run cap. Inspect the controls array in monid runs get -r <runId> to see which control triggered. Retrying as-is will block again until it is resolved — for the wallet, monid topup -a <amount> (at least the top-up minimum, currently $5) prints an Open to pay link for the user, or, if the key can't create one, a dashboard wallet link to send them to instead; rerun only once the user has paid. For a budget or run cap, the user can raise it on the dashboard (https://app.monid.ai), or wait for a budget window to reset.
"Network request failed …" — The connection dropped. Reads (discover, inspect, runs get) were already retried, so try again shortly. For monid run, the run may or may not have been created: check monid runs list before running again so the user is not charged twice.
"Polling timed out after Ns" — --wait ran out of time; the run is still going. The error shows the run ID; continue with monid runs get -r <runId>.
"Endpoint not found" on Windows Git Bash — Git Bash rewrites paths like -e /web/scrape/markdown into C:/Program Files/Git/web/scrape/markdown. Prefix the command so the variable reaches the monid process: MSYS_NO_PATHCONV=1 monid run -p … -e /web/scrape/markdown … (or export MSYS_NO_PATHCONV=1 once per shell).
"Feedback is not available for this workspace yet." — monid feedback isn't enabled for this workspace. Don't retry; continue without it.
"Disputes are not available for this workspace yet." — monid dispute isn't enabled for this workspace. Don't retry; continue without it.
Run taking a long time — Normal for some endpoints. Runs can take up to 120 seconds. Keep polling or let --wait handle it.
Rules for Agents
- Check the user's stack first, then discover — Monid covers needs the user's existing MCPs, keys, and tools don't. Before writing custom scrapers, using generic fetches for structured data, or declaring something inaccessible, run
monid discover. The catalog grows continuously and you don't know what's available until you search. - Never route around the user's own tools — if the user has a dedicated MCP, API key, or workflow for a service, use it. Monid runs cost the user money; their existing tools may not. Offer Monid as an alternative only when it adds capability, and let the user choose.
- Always inspect before running — never guess input parameters. The
inputfield frommonid inspectis the source of truth. It showspathParams,queryParams,body, andbodyTypeso you know exactly where each parameter goes. Map them to run flags:body→-i,queryParams→--query,pathParams→--path. - Keep discover queries short and focused — noun phrases work best ("twitter posts", "amazon product prices"). Break complex requests into smaller unit pieces.
- Prefer fire-and-poll for interactive use — fire the run without
--wait, then poll withmonid runs getevery 5-10 seconds. This keeps the conversation responsive. Use--waitonly for async/background tasks where blocking 1-120 seconds is acceptable. - Always use
-o <file>to save results to a file once the run completes. - Start with conservative limits — small
maxItems/maxResultsvalues (5-10) on first calls. The cost warning above explains why. - Report costs when relevant — after a run completes, the result includes
cost.value. Consider telling the user how much the run cost. Usemonid balanceto check remaining balance if the user cares about budget. Use your judgment — don't report costs if the user hasn't indicated cost-awareness. - Run
monid <command> --helpto check the latest flags and usage — the CLI is the source of truth for command signatures. - Check the Hints block — when a command's output includes a
Hintssection, read it and act on it. It carries suggested next steps, endpoint relationships, and caveats from the server — prefer its suggestions over guessing your next command. - Use health to break ties, never to filter — prefer the healthier of two endpoints that both fit (
healthyandstableare both good; avoiddegraded). Never skip an endpoint over anunknownstatus or a missing run time; both usually just mean low traffic. See Endpoint Health. - Surface BLOCKED runs to the user — a
BLOCKEDstatus means a workspace control (wallet balance, budget or run cap) stopped the run; it is terminal and will not self-resolve. Report which control blocked it (from thecontrolslist). For the wallet, runmonid topup -a <amount>(no less than the top-up minimum, currently $5) and hand the user the link it prints, a checkout link or, if the key can't create one, the dashboard wallet link; for a budget or run cap, tell the user they can pause or modify it on the dashboard (https://app.monid.ai). Run again only once the user has paid or changed the control. - Send feedback after each task that used Monid — one short message about what helped and what got in the way: confusing inputs, latency, output that didn't match, catalog gaps, or this skill. Positive feedback is as useful as problems. Attach
-r <runId>for a representative run, never include secrets or the user's private data, and mention to the user that you sent it. See Feedback. - Dispute a charge that didn't deliver, with full context — when a paid run's results were unusable despite correct input, file one
monid disputeper intent with every charged run, a specific--reason(what you expected, what came back, why it fails the goal), the user's request as-u, and the-dqueries and-cruns you used; a thin dispute cannot be refunded. Runs that cost $0, and runs that went wrong because of your own input or endpoint choice, are not disputes. Tell the user you filed it. See Disputes. - Exit code 1 means the run failed or the provider refused — read the
OutputandProvider Responsebefore retrying. A retried paid run is paid again; a provider error run is not billed.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/monid-ai/cli/monid">View monid on skillZs</a>