Discover

POST https://api.usegoro.ai/v1/discover

Describe the job in plain language. Goro ranks the catalog against it and returns the best matches, each with its price and a sample input you can fill in, so you can often go straight to run without inspecting first.

Request

Field	Type	Required	Notes
`query`	string	yes	What you are trying to accomplish. Must be non-empty
`limit`	integer		How many matches to return. Default 5, capped at 20. Must be a positive integer

curl -X POST https://api.usegoro.ai/v1/discover \
  -H "Authorization: Bearer $GORO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "tweets about ai agents", "limit": 3}'

Response

{
  "items": [
    {
      "slug": "twitter.search",
      "name": "Twitter search",
      "category": "social",
      "when_to_use": "Use when you need tweets about a topic, sentiment or chatter on X, mentions of a brand or person, or what people are saying right now.",
      "price": {
        "type": "usage_based",
        "min_micro": 2000,
        "min_usd": "$0.0020",
        "max_micro": 3000000,
        "max_usd": "$3.00",
        "billed_on_actual_usage": true,
        "per_unit_micro": 1200,
        "per_unit_usd": "$0.0012",
        "unit_label": "result",
        "summary": "$0.0012 per result, billed on actual usage (minimum $0.0020 per call), up to $3.00 per call"
      },
      "sample_input": {
        "sort": "Latest",
        "maxItems": 20,
        "searchTerms": "<searchTerms>"
      }
    }
  ]
}

Field	Type	Notes
`items`	array	Matches, best first. Can be empty
`items[].slug`	string	The identifier to pass to `inspect` and `run`
`items[].name`	string	Human name
`items[].category`	string	Catalog category, for example `social`, `search`, `maps`
`items[].when_to_use`	string	Guidance on when this tool is the right one
`items[].price`	object	See below
`items[].sample_input`	object	A ready-to-fill input object

Ranking is lexical and deterministic: the same query returns the same order every time. Matches that score zero are dropped, so a query nothing answers returns {"items": []} rather than a list of bad guesses.

sample_input

sample_input is built from the tool’s own input schema. It contains every required field, plus every optional field that declares a default. Values come from the schema’s examples, then its defaults, then its enums. A required field with none of those appears as a placeholder like "<searchTerms>", which you are expected to replace. It is a starting point, not a validated input. run validates what you actually send.

price

price is the same object inspect and run return. Its fields depend on type.

Field	Type	Present on	Notes
`type`	string	all	`usage_based`, `metered`, `per_call`, `per_call_variant` or `per_result`
`summary`	string	all	One-line human description
`per_unit_micro`, `per_unit_usd`	integer, string	`usage_based`, `metered`	The rate you pay per unit. Absent on a `usage_based` tool with no published rate
`unit_label`	string	`usage_based`, `metered`	What one unit is: `profile`, `page`, `second of audio`
`min_micro`, `min_usd`	integer, string	`usage_based`, `metered`	Floor for a call that delivered something
`max_micro`, `max_usd`	integer, string	`usage_based`, `metered`	Ceiling. You are never charged above it
`billed_on_actual_usage`	boolean	`usage_based`, `metered`	Always `true`. The total depends on the call, so `max_usd` is a maximum and not a price
`base_micro`, `base_usd`	integer, string	`per_call`, `per_call_variant`, `per_result`	Flat component. On `per_call` it is the entire price; on `per_call_variant` it is `default_variant`’s price
`selector`	string	`per_call_variant`	The input field whose value picks the price, for example `resolution`
`variants`	array	`per_call_variant`	Every priced option, cheapest first: `{value, price_micro, price_usd}`. Each is an exact price, not a starting point
`default_variant`	string	`per_call_variant`	The option billed when you omit `selector` from the input
`per_result_micro`, `per_result_usd`	integer, string	`per_result`	Charged per row
`max_results_cap`	integer	`per_result`	Rows past this are neither delivered nor billed

Most of the catalog is usage_based: the total follows what the call actually did, floored at min_micro and capped at max_micro. The image tools are per_call, one flat price with no ceiling to read. The voice tools are metered, an exact rate against the size of your request, with a ceiling on top. The nano banana image tools are per_call_variant: flat and exact like per_call, but the price depends on which resolution you ask for, and every option’s price is listed in variants. per_result is part of the contract but nothing in the catalog uses it today, so handle it if you parse price generically. A settled run that cost nothing is charged nothing: cost_micro comes back 0 and free comes back true. See run.

On a usage_based or metered tool, max_usd is a ceiling and the hold Goro places is sized from what you request, so it usually sits well below that number. On a per_call tool there is no ceiling: base_usd is what the call costs. Every tool’s page in the catalog says which it is.

Errors

Status	`code`	When
400	`validation_error`	`query` missing or empty, or `limit` is not a positive integer
401	`unauthorized`	Missing or invalid API key

Discovery is free. It places no hold and charges nothing.

Then inspect the match

Read the full input schema before you run it.

Guide

CLI reference

API reference

Tools

Request

Response

sample_input

price

Errors

Then inspect the match

​Request

​Response

​sample_input

​price

​Errors

Then inspect the match

Request

Response

sample_input

price

Errors