# Quickstart

Quickstart

# Your first call, start to finish

Four steps: create an account, collect the key the console has already made for you, run one curl against a real endpoint and read the shared response envelope.

## Connect with browser sign-in

Open [agent setup](https://www.monocrawl.com/dashboard/onboarding), choose your app and sign in. The connection command and copyable skill contain no API key. Ask your agent to check your balance to verify the connection for free, then continue to your dashboard. See the [connection guide](https://www.monocrawl.com/docs/integrations) for all supported apps and the CLI installer.

## Choose a useful first result

Pick a [common job](https://www.monocrawl.com/docs/recipes) to see its calls in order and current catalogue costs. Find creators from [Instagram reels](https://www.monocrawl.com/docs/instagram-creators), turn a video into text, or preview a brand monitor. Search docs by task or parameter name when you need a particular capability. Use a free preview and an explicit credit ceiling before a workflow that makes several calls.

## Create an account

Sign up with an email address. New accounts start with 150 free credits, with no card required. Use them to try the endpoints you need; each operation has its own price.

[Create an account](https://www.monocrawl.com/auth/register)

## Collect your key

You do not have to create one. The first time you open the console overview, an account with no key gets one provisioned server-side. You can reveal or copy it from the setup page or API keys page. It looks like this:

**api key**

```
mn_4pQ8Zr1nKuT0aWxYb7cLdE3fGh9JmNpQsRtUvWxYz01
```

Prefix

Every key starts with mn_ — three characters, then 43 of base64url randomness, 46 in total.

Reveal or copy

New keys are masked by default. Use Reveal or Copy on the API keys page whenever you need the full value.

Replaceable

Older keys cannot be recovered. Create a replacement if needed. Keys are independent of your balance.

Manage keys — names, per-key credit limits, revocation — at `/dashboard/api/keys`. Full detail in [authentication](https://www.monocrawl.com/docs/authentication).

## Make the call

`github/profile` has been proven by real traffic and has a list price of 1 credit per successful uncached call. Substitute your key and run it.

**terminal**

```
curl "https://www.monocrawl.com/v1/github/profile?handle=torvalds" \
  -H "x-api-key: mn_your_key_here"
```

An illustrative successful response, not a fresh request or a guarantee of these field values:

**200 · application/json**

```
{
  "success": true,
  "platform": "github",
  "endpoint": "/v1/github/profile",
  "data": {
    "id": 1024025,
    "handle": "torvalds",
    "name": "Linus Torvalds",
    "url": "https://github.com/torvalds",
    "avatar_url": "https://avatars.githubusercontent.com/u/1024025?v=4",
    "bio": null,
    "company": "Linux Foundation",
    "location": "Portland, OR",
    "website": null,
    "email": null,
    "followers": 245310,
    "following": 0,
    "public_repos": 8,
    "public_gists": 0,
    "type": "User",
    "created_at": "2011-09-03T15:26:22Z",
    "updated_at": "2026-08-14T07:12:44Z"
  },
  "credits_used": 1,
  "credits_remaining": 99,
  "request_id": "req_4f2b8c1d09ae37b562",
  "cached": false
}
```

## Read the envelope

These are the standard success-envelope fields. Errors replace data with an error object and may omit the balance; payload fields inside data remain endpoint-specific. Batch has a separate wrapper, and streamed searches return their envelope in the final result event.

| Field | Type | Meaning |
| --- | --- | --- |
| `success` | boolean | true on a 200. On any error it is false and an error object replaces data. |
| `platform` | string | The platform segment of the path you called. |
| `endpoint` | string | The resolved route, normally /v1/{platform}/{endpoint}; sandbox results use /sandbox. |
| `data` | object | The endpoint-specific payload. Many lists use items, count and cursor, but bundles and service operations can differ. |
| `credits_used` | number \| null | Confirmed credits used. Synthetic sandbox examples and confirmed uncharged/refunded failures use 0. An unresolved production outcome can report null; inspect error.details.billing_status. |
| `credits_remaining` | number | Wallet balance observed during the call. Present on success; errors may omit it when unknown. |
| `request_id` | string | req_ plus 18 hex characters. Quote it in support mail; it is also the ledger reference. |
| `cached` | boolean | true when the answer came from the shared response cache instead of the upstream. |

Production `/v1` never substitutes a sample when a provider fails: it returns a typed error. Confirmed uncharged or refunded failures report `credits_used: 0`; unresolved accounting can report null, so retain the request ID and reconcile before retrying. A response can carry `synthetic: true` only when you deliberately call `/sandbox` — [details in errors](https://www.monocrawl.com/docs/errors#degraded-responses).

## The same call from TypeScript or Python

No SDK required — it is a GET with one header. Check `success` before touching `data`; errors carry a typed `error` object instead. Keep the key in the environment, never in the file.

### typescript

```
const key = process.env.MONOCRAWL_API_KEY;
if (!key) throw new Error('Set MONOCRAWL_API_KEY on your server.');
const res = await fetch(
  "https://www.monocrawl.com/v1/github/profile?handle=torvalds",
  { headers: { "x-api-key": key } },
);
const body = await res.json();

if (!body.success) {
  // one error shape for every endpoint — see /docs/errors
  throw new Error(`${body.error.type}: ${body.error.message}`);
}

console.log(body.data, "credits left:", body.credits_remaining);
```

### python

```
import os
import requests

res = requests.get(
    "https://www.monocrawl.com/v1/github/profile?handle=torvalds",
    headers={"x-api-key": os.environ["MONOCRAWL_API_KEY"]},
    timeout=60,
)
body = res.json()

if not body["success"]:
    # one error shape for every endpoint — see /docs/errors
    raise RuntimeError(f"{body['error']['type']}: {body['error']['message']}")

print(body["data"], "credits left:", body["credits_remaining"])
```

## Try a few more

| Endpoint | Required param | Credits | What it returns |
| --- | --- | --- | --- |
| `GET /v1/github/profile` | `handle` | 1 | Public profile, follower counts and repository totals for a GitHub user. |
| `GET /v1/hackernews/search` | `query` | 1 | Search Hacker News stories and comments. |
| `GET /v1/bluesky/profile` | `handle` | 1 | A public Bluesky account — handle or DID. |
| `GET /v1/youtube/channel` | `channelId or handle` | 1 | A YouTube channel by id, @handle, legacy username or URL. |

Credits are read from the registry on every render. For the full list and each endpoint's parameter schema, call `GET /v1/utility/endpoints` — it costs 0 credits — or browse the [platform reference](https://www.monocrawl.com/docs/platforms). Then read the [API reference](https://www.monocrawl.com/docs/api-reference) for pagination, batching and path parameters.