MeshArc

mesharc

MeshArc API 用の Python クライアントです。URL を渡すと、クリーンなコンテンツと、変更内容の記録が返ってきます。

• スクレイピング：1 ページまたは複数ページをまとめて取得できます。Markdown、テキスト、HTML、リンク、構造化フィールド、スクリーンショットに対応しています。
• クロール：事前にプロジェクトを設定せずにサイト全体をクロールできます。監視する価値があると分かったら、プロジェクトとして登録できます。
• マッピング：サイトマップに記載された内容を取得する前に、サイトが宣言している内容をマッピングできます。
• 検索：URL が分からないページをウェブで検索し、同じ呼び出しで各結果のページを読み取れます。
• 質問：エージェントに質問できます。エージェントは検索してページを読み、回答します。スキーマを指定すると、その形式で回答し、回答の根拠となったページも示します。（mesharc.dev ではまだ利用できません。）
• 監視：検索や質問を毎時、毎日、毎週実行し、回答を前回のものと比較して、変更があったときに Webhook で通知できます。（mesharc.dev ではまだ利用できません。）
• ウォッチ：サイトを継続的に監視できます。プロジェクト、スケジュール実行、変更記録を使って、追加、削除、変更されたページをフィールド単位で確認できます。

Python 3.10 以降に対応しています。依存関係は 1 つ（httpx）です。完全な型情報を備えています。

インストール

pip install mesharc

認証

すべての呼び出しに API キーが必要です。アプリの Settings → API keys でキーを作成してください。キーは一度だけ表示されます。キーをクライアントに渡すか、MESHARC_API_KEY に設定してクライアントを引数なしで作成します。

from mesharc import MeshArc

arc = MeshArc("mesharc_...")
# or, with MESHARC_API_KEY in the environment:
arc = MeshArc()
# options: MeshArc(api_key, timeout=150.0, max_retries=2)

キーは api.mesharc.dev に対して、ベアラーヘッダーとしてのみ送信されます。

キーには、作成時に設定したスコープ（read、write、admin）、アクセスできるプロジェクトの任意のリスト、有効期限、レート制限が付与されます。キーで使用できないルートにアクセスすると 403 が返され、アクセスできないプロジェクトにアクセスすると 404 が返されます。

クイックスタート

from mesharc import MeshArc

arc = MeshArc("mesharc_...")

page = arc.scrape("https://example.com/pricing")
print(page["markdown"])
print(page["verdict"], page["method"], page["credits"])   # ok crawler 1

scrape はページが返ってくるまでリクエストを開いたままにします（デフォルトでは 60 秒）。そのため、通常のページではポーリングする必要はありません。

ページの読み取り

1 ページ

page = arc.scrape("https://quotes.toscrape.com/js/", config={"render_js": "always"})

config には、プロジェクトで使用できる任意の設定を、API 名（render_js、only_main_content、formats、max_tier、wait_for_selector、actions、…）で指定します。デフォルト値を含む全リストは mesharc.dev/docs/configuration にあります。

page = arc.scrape_one(
    "https://example.com/",
    formats="markdown,text,cleanHtml",     # which bodies to return
    timeout_s=120,                         # how long the API holds the request (120 max)
    idempotency_key="pricing-2026-09-18",  # the same key returns the first answer for 24 h
)

複数ページ

URL のリストを渡すとバッチ処理になります。ホストごとにグループ化され、設定で許可される場合は並列に取得され、URL ごとに 1 行ずつ返されます。

batch = arc.scrape(["https://a.com/", "https://b.com/x"], config={"concurrency": 4})
for row in batch["pages"]:
    print(row["url"], row["httpStatus"], row["verdict"], row["credits"])

arc.scrape(urls, wait=False) はすぐにバッチ ID を返します。arc.batch(id, wait=True) で後から処理を完了できます。ポーリングの代わりに通知を受け取るには webhook_url= を渡します（batch.finished。一度だけ返されるシークレットで署名されます）。

ページの形式

スクレイピング、クロール、プロジェクトのいずれから取得されたかにかかわらず、すべてのページ行に同じフィールドが含まれます。

フィールド	意味
markdown、text、cleanHtml、html、links、fields、screenshot	指定したコンテンツ
httpStatus	サイトから返されたステータス
verdict	ok、thin（短いもののページである）、blocked（拒否された、または 404）、skipped
errorCode	OK、または発生した問題を示すコード：BLOCKED、NOT_FOUND、TIER_LIMIT、CAPTCHA、LOGIN_REQUIRED、RATE_LIMITED、TIMEOUT …
shape、warnings、signals	短いページのマークアップからその種類が分かる場合は listing / table / form、short、判定理由
method、tier、climbedTo	ページを読み取ったエンジン（crawler、tls、minted、browser、browser-residential、…）、そのティア、拒否されたページについてどこまで段階を上げたか
credits、billedAs	使用したクレジット数と、取得に使われたものとは異なる場合の課金対象の段階
words、language、head、reason、crawledAt	サイズ、言語、head フィールド、判定理由の文、取得日時

サイトに拒否されたページは課金されず、404 も同様です。

サイトをクロールする

job = arc.crawl(
    "https://docs.example.com",
    limit=200,                          # page budget
    maxDepth=3,                         # link hops from the seed
    includePaths=["/docs/*"],
    crawlMode="sitemap_first",          # what the sitemap declares first, then links
    maxTier="browser",                  # how far a refused page may climb
    scrapeOptions={"formats": ["markdown", "links"]},
    config={"crawl_delay_ms": 500},     # any project setting, directly
)

for page in job.pages():                # follows the cursor while the crawl runs
    print(page["url"], page["words"])
print(job.status, job.envelope["counts"], job.envelope["creditsUsed"])

crawl はすぐにハンドルを返します。job.pages() はページが到着するたびに返し、クロールが完了すると終了します。wait=True は完了までブロックします。job.wait()、job.refresh()、job.cancel() はそれぞれ名前のとおりの動作をします。arc.get_crawl(id) を使うと、別の場所で開始されたクロールに再接続できます。

一度限りのクロールは30日後に期限切れになります。監視する価値のあるサイトなら、次のようにします。

project = job.keep(name="Docs", schedule="weekly")

オプションの webhook=（{"url", "events", "metadata", "include"}）には、crawl.started、crawl.page（1メッセージあたり50ページ）、crawl.completed の通知が送られます。署名シークレットは job.webhook_secret として一度だけ返されます。"include": ["markdown"] を指定すると、crawl.page メッセージに各ページの Markdown も含まれます。1メッセージあたり約1 MBまでです。収まらないページ、または保存されていないページは、"markdown": null と markdownOmitted（too_large または not_stored）、および contentUrl として返されます。これはキーを使って読み取る API パスです（job.page(url) でも同じ内容を読み取れます）。events を省略した場合と同様に、イベントには crawl.page が必要です。

サイトをマップする

for u in arc.map("https://docs.example.com"):
    print(u["url"], u["lastmod"])

details = arc.map_details("https://www.gov.uk/", search="visa", limit=500)
print(details["totals"], details["creditsUsed"])   # {'files': 29, 'urls': 508431, …} 29

マップの料金は、読み取ったサイトマップファイル1つにつき1クレジットです。ほとんどのサイトではファイルは1つです。

ウェブを検索する

out = arc.web_search(
    "python packaging guide",
    limit=5,                            # 1 to 10 results
    freshness="month",                  # hour | day | week | month | year
    include_domains=["python.org"],     # exclude_domains= too; an exclude wins
    scrape=True,                        # each result's page as markdown as well
)

if out["status"] == "blocked":          # every engine refused; nothing was charged
    print(out["attempts"])
else:
    for hit in out["data"]:
        print(hit["position"], hit["title"], hit["url"], hit["snippet"])
        if hit.get("page"):
            print(hit["page"].get("markdown", "")[:200])
print(out["engine"], out["cached"], out["creditsUsed"])

again = arc.get_search(out["id"])       # a search started earlier, by id
for s in arc.searches(q="python"):      # the workspace's searches, newest first
    print(s["id"], s["query"], s["status"], s["resultCount"], s["creditsUsed"])

news = arc.web_search("python release", news=True, freshness="day")   # the engines' news results
for hit in news["data"]:
    print(hit["publisher"], hit["age"], hit["title"])                  # who published it, and how long ago ('20h')
more = arc.web_search("python packaging guide", page=2)               # results 11-20

web_search は結果を待ち、結果一式を返します。ヒットは data の下にあります。検索の状態は queued、running、done、blocked、error のいずれかです。すべての検索エンジンが拒否した場合の blocked は、例外ではなく返されます。error では MeshArcError が発生します。スクレイピングを行う検索は、ページが到着するまで running のままです。scrape= には辞書も指定でき、そのまま送信されます（{"formats": ["markdown", "links"], "maxCredits": 20}）。country= と lang= では検索する地域と言語を指定します。wait=False はすぐに返し、timeout_s はクライアントがポーリングするまで API がリクエストを保留する時間です（デフォルトは60秒、最大120秒）。

news=True を指定すると、ウェブではなく検索エンジンのニュース結果を検索します（1回の検索でどちらか一方のみ）。各ニュースヒットには、検索エンジンが示したとおりの publisher と age（"20h"）も含まれます。page= は結果ページを示し、1～10を指定します。2ページ目は結果11～20で、各ページはそれぞれ独立した検索として課金されます。news= と page= には、これらの機能に対応した API が必要です。これらの機能は API の機能ブランチにあり、まだ mesharc.dev では利用できません。

検索には書き込み可能なキーが必要で、クレジットを消費します。結果ページの料金は、そのページを読み取った検索エンジンに対して発生します。すべての検索エンジンが拒否した結果ページは無料です。完了から1時間以内（ニュースの場合は10分以内）に同じ条件（クエリ、news、page、country、lang、freshness、ドメイン）で検索すると、キャッシュから結果が返され（cached が true）、結果ページの料金は発生しません。スクレイピングしたページには、キャッシュの有無にかかわらず料金がかかります。

arc.search(project_id, q) は別の機能です。ウェブではなく、プロジェクトに保存されたページを検索します（以下を参照）。

エージェントに質問する

エージェントのルート（/agent）は、まだ mesharc.dev では利用できません。ウェブ検索は利用できます。クライアントと MCP ツールはエージェントに対応する準備ができています。エージェントの Webhook、connection_id、continue_()、field_sources にも、これらの機能を備えた API が必要です。これらは API の機能ブランチにあり、まだ mesharc.dev には反映されていません。

エージェントは質問を受け取り、ウェブを検索し、サイトをマッピングしてページを自動で読み、使用したページとともに回答します。スキーマを渡すと、その形式で回答が返ります。

run = arc.agent(
    "What does each plan on example.com cost per month?",
    urls=["https://example.com/pricing"],   # pages to start from, up to 20; omit to let it search
    allowed_domains=["example.com"],        # keep it to these sites, up to 20
    schema={                                # a JSON Schema of type object or array
        "type": "object",
        "properties": {"plans": {"type": "array", "items": {"type": "object", "properties": {
            "name": {"type": "string"}, "monthly": {"type": "number"}}}}},
    },
    max_credits=500,                        # the most the run may spend: 1 to 100,000, 2,000 by default
    max_steps=20,                           # the most steps it may take: 1 to 100, 40 by default
)

out = run.wait()                            # blocks until it finishes; the envelope
print(out["status"], out["creditsUsed"], out["steps"])
print(run.data)                             # {'plans': [...]}, matching the schema
for src in run.sources:                     # the pages the answer rests on
    print(src["url"], src["title"])
print(run.field_sources)                    # {'plans[0].monthly': {'url': ..., 'pageId': ...}, ...}

agent は、キューに入っている、または実行中の AgentRun をすぐに返します。プロンプトは最大 10,000 文字です。timeout_s= を指定すると、回答が得られるまで API がリクエストを保留します（最大 120 秒）。スキーマを指定しない場合、回答は {"text": ...} です。field_sources は回答の各値の出所を示します。値のパス（"plans[0].monthly"、リスト形式の回答なら "[2].name"）に対応する {url, pageId} は、実行中に読み込んだページです。

run = arc.agent(
    "What does each plan on example.com cost per month?",
    webhook={"url": "https://hooks.example.com/mesharc", "events": ["agent.completed", "agent.failed"]},
    connection_id="conn_...",               # run on one of the workspace's own LLM connections
)
print(run.webhook_secret)                   # once: the secret the webhook's messages are signed with

webhook= には URL、または {"url", "events", "metadata"} を指定します。Webhook には agent.started、agent.action、agent.completed、agent.failed、agent.cancelled が通知されます（デフォルトでは 5 つすべて）。署名シークレットは run.webhook_secret として一度だけ返されます。停止した実行のハンドルから continue_() が返すハンドルにも、停止した実行のシークレットが引き継がれます（新しい実行でも同じ Webhook が使われます）。get_agent で再取得した実行にはシークレットがありません。connection_id= を指定すると、ワークスペース独自の LLM 接続のいずれかを使ってエージェントを実行します。モデル、キー、料金はその接続のものが使われます。

動作を確認するには、トレースを追跡します。

run = arc.agent("Who maintains the httpx library, and where is it developed?")
for event in run.trace():                   # follows the run until it ends
    print(event["seq"], event["kind"], event["text"])
print(run.wait()["data"])                   # {'text': '...'}

kind は start、resume、continue、model、search、fetch、render、map、select、extract、lookup（データプロバイダーのレコード）、propose、tool、busy、finish のいずれかです。trace(after=seq) は、すでに確認したイベントの後から再開します。follow=False を指定すると、存在するイベントを返して終了します。

run.cancel()                                # {'id': ..., 'status': 'cancelled'} if it was queued, 'cancelling' if running
run.refresh()                               # the run as it stands now

again = arc.get_agent(run.id)               # a run started earlier, by id
for r in arc.agent_runs(status="done"):     # the workspace's runs, newest first
    print(r["id"], r["status"], r["creditsUsed"], r["prompt"])
from datetime import date
for r in arc.agent_runs(model="openai:gpt-5.4-mini", since="2026-10-01", until=date.today()):
    print(r["id"], r["model"], r["createdAt"])

実行の状態は queued、running、done、error、cancelled、credit_limit のいずれかです。wait() は、状態が done、cancelled、または credit_limit で停止した実行を返します。credit_limit は実行が max_credits に達した状態で、見つかった内容は data["partial"] に格納されています。状態が error の場合は、API のテキストを含む MeshArcError 502 job_failed を送出します。それ以外の不明な終了状態の場合も、Node クライアントと同様に例外を送出します。キャンセルすると、キューに入っている実行は直ちに停止し、実行中のものは次のステップの前に停止します。使用済みのクレジットは請求されます。arc.cancel_agent(id) を使うと、ハンドルがなくても実行 ID で同様にキャンセルできます。

agent_runs は、status、実行時に指定した名前での model、および実行時刻で絞り込めます。since 以降、until より前を指定でき、どちらも ISO 8601 の日付または日時文字列、あるいは date／datetime です。日付は UTC の午前 0 時として扱われます。タイムゾーンのない日時は UTC として解釈されます（そのため、単純な datetime.now() はローカル時刻を UTC として解釈します。代わりに datetime.now(timezone.utc) を渡してください）。

credit_limit で停止した実行は、新しい予算で続行できます。

out = run.wait()
if out["status"] == "credit_limit":
    more = run.continue_(max_credits=1_000)   # a new run, on the same thread
    print(more.continues_run_id)              # run.id
    print(more.wait()["data"])                # the full answer, replacing the partial one

continue_() は、新しい実行の AgentRun を返します。停止した実行の続きから再開し、読み込み済みのページを保持します（再度料金は発生しません）。Webhook も引き継がれ、そのシークレットは新しいハンドルの webhook_secret で引き続き取得できます。max_credits と max_steps は新しい実行独自の値です。省略すると、停止した実行の値が使われます。停止した実行を再取得すると、その continued_by に新しい実行の名前が設定されています。クレジット上限で停止していない実行、すでに続行された実行、または保存済みの進行状況がない実行では、コード conflict の MeshArcError 409 が発生します。保存期間を過ぎた実行では、410 expired が発生します。

実行には書き込み可能なキーが必要で、クレジットを消費します。読み込むページごとに読み取り料金が発生します（拒否されたページは無料です）。また、モデルのトークンにはモデルプロバイダーの料金に 20％を加えた料金がかかります。ワークスペース独自の接続では、1,000 トークンあたり 1 クレジットです。これらの料金はすべて max_credits の範囲内です。実行は 7 日間保存されます。それ以降に get_agent を呼び出すと、ステータス 410、コード expired の MeshArcError が発生し、trace() は何も出力せずに終了します。

フォローアップと会話

mesharc.dev ではまだ利用できません： このセクションのすべての機能には、API の機能ブランチで開発中の機能を備えた API が必要です。

first = arc.agent("Which plans does example.com sell?", urls=["https://example.com/pricing"])
first.wait()
nxt = first.follow_up("And which of them include SSO?")   # the same conversation
print(nxt.wait()["data"])

for c in arc.conversations(q="example.com"):              # the latest message first
    print(c["id"], c["messages"], c["title"])
thread = arc.conversation(first.id)                        # every run in it, oldest first, under "runs"

フォローアップでは、会話でそれまでに尋ねられ、見つかったすべての内容に対する回答を行います。また、会話で閲覧したページは、無料で何度でも再度読み込めます。リクエストは独立しており、follow_up が受け取る内容は agent と同じです。また、フォローアップ自身の処理に対して料金が発生します。会話の最新メッセージのみが、処理完了後に一度だけフォローアップできます。それ以外の場合は MeshArcError 409 conflict（最新メッセージを示します）が返されるか、メッセージ数が 30 を超えているとエラーになります。

保存済みログイン、データプロバイダー、提案

mesharc.dev ではまだ利用できません： このセクションのすべての機能には、API の機能ブランチで開発中の機能を備えた API が必要です。

run = arc.agent(
    "How many employees does Stripe have, and what was Apple's revenue last year?",
    data_connections=["conn_pdl", "conn_fmp"],   # the workspace's data providers, one per provider
    logins="auto",                               # the saved logins it may sign in with (the default)
    proposals=True,                              # it may propose things to watch
)

data_connections= では、ワークスペースのデータプロバイダー接続（以下の arc.connections）を最大 2 つ指定します。企業データ用の People Data Labs と、財務データ用の Financial Modeling Prep が対象です。エージェントは、ユーザー自身のキーを使ってデータを検索できます。料金はプロバイダーから請求され、MeshArc のクレジットは消費されません。見つかった各レコードは、run.sources に {url, title, provider} として追加されます。url はそのレコードの取得元となったリクエストであり、ユーザーのキーが含まれることはありません。エージェントはサインアウト状態でページを読み込み、アカウントが必要なページでは、サイトごとにワークスペースに保存されたログイン情報（arc.logins）を使ってページごとにサインインします。使用可能なログイン情報は logins= で指定します（デフォルトではすべて、"none"、または ID のリスト）。login_id= は、ID が 1 つのリストを指定する従来の形式です。ログイン情報はデプロイごとに有効化します。proposals=True を指定すると、エージェントはサイトのクロール、検索または質問の定期実行を提案できます。メンバーが承認するまで、何も作成されません（arc.proposals）。

モニター：スケジュールに従って繰り返す検索または質問

モニター（arc.monitors、/monitors ルート）には、その機能に対応した API が必要です：この機能は API の機能ブランチにあり、mesharc.dev にはまだありません。以下では、上限、アラート、レコード、トーンについて説明します。

monitor = arc.monitors.create(
    "search",                                         # or "agent"
    {"query": "mesharc", "freshness": "day"},         # a POST /search or POST /agent body, in the API's own names
    "daily",                                          # hourly | daily | weekly
    name="Mentions",
    webhook="https://hooks.example.com/mesharc",      # told search.changed / agent.changed
)
print(monitor["webhookSecret"])                       # once

for r in arc.monitors.runs(monitor["id"]):            # newest first
    print(r["createdAt"], r["status"], r["changed"], r["summary"])

press = arc.monitors.create("search", {"query": "mesharc", "sources": ["news"]}, "hourly")   # a news monitor
arc.monitors.update(monitor["id"], schedule="weekly")  # only what is not None is sent
arc.monitors.update(monitor["id"], webhook="")         # the empty string removes the webhook

各実行は通常の検索またはエージェントの実行で、1 回分として課金されます。検索の場合は新規、除外、移動した結果、エージェントの場合は回答に追加、変更、削除された値が、直前に回答を返した実行と比較されます。実行の refId は、その実行が行った検索またはエージェントの実行です（arc.get_search／arc.get_agent）。

request は API 独自の名前（キャメルケース）を使った POST /search または POST /agent の本文です（{"query": ..., "includeDomains": [...]}、{"prompt": ..., "schema": ..., "maxCredits": ...}）。web_search や agent の Python 引数ではありません。そのため、ニュースモニターでは "sources": ["news"] を指定します。web_search(news=True) はその引数をこの形式にマッピングしますが、monitors.create はマッピングしません。検索モニターが読み取るのは結果ページのみのため、scrape は拒否されます。baseline_id= には、最初の実行と同じリクエストを使った完了済みの検索またはエージェントの実行を指定します。この実行は再課金されません（検索の場合、ベースラインの limit はモニターの limit 以上である必要があります）。指定しない場合は、初回の実行が今すぐ開始されます。

メソッド	動作
monitors.create(kind, request, schedule, name=None, webhook=None, baseline_id=None, idempotency_key=None, budget=None, alerts=None, add_to_project=None, rows=None, destination=None, sentiment=None)	検索またはエージェントのリクエストをスケジュールに従って実行します
monitors.list(kind=None) · monitors.get(id)	ワークスペースのモニター一覧（それぞれ lastRun を含む）、または指定したモニター
monitors.overview(kind=None)	スケジュールに登録されたすべての項目（プロジェクトとモニター）を、次回と前回の実行、今月の使用額、見積もり、上限とともに表示します
monitors.update(id, name=None, schedule=None, status=None, webhook=None, budget=, alerts=, add_to_project=, rows=, destination=, sentiment=)	None でない項目を変更します。status は active または paused、webhook="" は Webhook を削除します
monitors.pause(id) · monitors.resume(id)	スケジュールを停止または再開します。一時停止中に実行時刻を過ぎた分は、再開時に 1 回実行されます
monitors.run(id, idempotency_key=None)	今すぐ実行します。実行中は 409 conflict が返されます
monitors.runs(id, limit=25)	changed、summary、diff を含む実行履歴を、next に従って取得します
monitors.delete(id)	モニターとその実行履歴を削除します。実行によって行われた検索とエージェントの実行は残ります
monitors.rows(id, active=None, q=None) · monitors.row(id, key) · monitors.row_events(id, run_id=None, kind=None) · monitors.export_rows(id, path, dataset="rows", fmt="csv")	エージェントモニターのレコード、履歴付きの単一レコード、変更内容、すべてをファイルとして取得します

plans = arc.monitors.create(
    "agent", {"prompt": "List example.com's plans with their monthly price", "urls": ["https://example.com/pricing"],
              "allowedDomains": ["example.com"]}, "weekly",
    budget={"perRun": 300, "perMonth": 1500},          # credits; 0 or left out is no cap
    alerts={"email": True, "chatUrl": "https://hooks.slack.com/services/..."},
    rows={"path": "plans", "key": "name"},             # follow the answer's list, plan by plan
)
for row in arc.monitors.rows(plans["id"]):
    print(row["key"], row["attrs"], row["sources"])   # its columns, and the page each was read on
for event in arc.monitors.row_events(plans["id"]):    # added, changed (before and after), gone
    print(event["kind"], event["key"])

budget は各実行に上限を設け（perRun はエージェントモニターの maxCredits を引き下げます）、月間の上限も設定します（perMonth を超える実行はスキップされ、Webhook には月に 1 回 budget.reached が通知されます）。alerts は、実行で新しい情報が見つかったときに、ワークスペースの実行通知メールとチャットメッセージ（Slack、Discord、Teams、Google Chat の受信用 Webhook）を送信します。検索モニターの add_to_project は、そのプロジェクトのサイトで見つかった新しい結果をプロジェクトに追加します。エージェントモニターの rows は、リスト形式の回答をレコードごとに追跡し、destination は各実行後にレコードを書き出します。ニュースモニターの sentiment={"connectionId": ..., "only": ["negative"]} は、ワークスペースの LLM 接続のいずれかを使って各実行の新しい結果を評価し（1,000 トークンあたり 1 クレジット）、チャットとメールを指定したトーンのみに絞ります。update は budget、alerts、sentiment 全体を置き換えます（設定しない場合は {}）。add_to_project="" と destination="" はそれぞれの設定を削除します。

モニターの作成と実行にはクレジットがかかります。書き込み可能なキーが必要なのは、monitors.list、monitors.get、monitors.runs 以外のすべての呼び出しです。Webhook のシークレットは、設定した呼び出しで webhookSecret として一度だけ返されます。arc.monitor() は別の機能です。ワークスペースのジョブキューで、キューに登録されているジョブと実行中のジョブを確認できます（以下を参照）。

テーブル上のエージェント

まだ mesharc.dev では利用できません： このセクションのすべての機能には、API のフィーチャーブランチにある次の機能が必要です。

table = "Company,Website\nAcme,acme.com\nGlobex,globex.com\n"
ask = dict(csv=table, max_credits_per_row=300, urls=["{{Website}}"],
           schema={"type": "object", "properties": {"plan": {"type": "string"}, "price_month": {"type": "number"}}})
print(arc.agent_batches.preview("What does {{Company}} charge for its cheapest plan?", **ask)["estimate"])
batch = arc.agent_batches.start("What does {{Company}} charge for its cheapest plan?", **ask, concurrency=3)
arc.agent_batches.wait(batch["id"])
for row in arc.agent_batches.rows(batch["id"]):
    print(row["values"]["Company"], row["status"], row["data"])
arc.agent_batches.export(batch["id"], "prices.csv")

1 行につきエージェントを 1 回実行します。行の列に入力されたプロンプトと開始 URL は {{column}} と記述し、schema（オブジェクト型）に沿った回答が行の新しい列になります。テーブルは csv またはオブジェクトのリストである rows として送信します。max_credits_per_row は必須です。各行はそこで処理を止め、実際に使用した分だけ課金されます。バッチ全体の消費量は、行数 × 上限を超えません。ただし、開始時の残高がそれより少ない場合は残高が上限になります。支払いができなくなった行は無料で skipped になります。allowed_domains を指定しない場合、各行は自身の URL と同じサイト内にとどまります。[] を指定すると制限が解除されます。preview は処理を開始せずに、すべてを確認して費用を見積もります。login_id と data_connections は agent() と同様に、すべての行に適用されます。

メソッド	機能
agent_batches.preview(prompt, csv=, rows=, max_credits_per_row=, ...)	実行内容、実行できない行とその理由、最初のプロンプト、見積もりを確認します。無料です
agent_batches.start(prompt, ..., webhook=None, idempotency_key=None)	バッチを開始します。webhookSecret は一度だけ返され、Webhook には agent.batch.finished が一度だけ通知されます
agent_batches.get(id, offset=0, limit=50, status=None) · agent_batches.rows(id, status=None) · agent_batches.wait(id)	行の 1 ページ分を取得します。すべての行を取得します。終了するまで待機します
agent_batches.list() · agent_batches.cancel(id) · agent_batches.export(id, path, fmt="csv")	バッチを一覧表示します。1 つを停止します。回答を含むテーブルをファイルとして出力します（数式として始まる CSV セルはテキストとして書き込まれます）

バッチは 7 日間保持されます。その後、get は MeshArcError 410 expired を発生させます。

トリガー、提案、月額費用

まだ mesharc.dev では利用できません： このセクションのすべての機能には、API のフィーチャーブランチにある次の機能が必要です。

arc.triggers.create(
    {"kind": "project", "id": project["id"]},
    {"type": "agent", "prompt": "Summarise what changed on {{url}}", "maxCredits": 300},
    when={"kinds": ["modified"], "paths": ["/pricing*"]},
    limits={"cooldownMinutes": 60, "maxPerDay": 5},
)
for p in arc.proposals.list():                 # what agents proposed to watch, waiting
    print(p["kind"], p["name"], p["estimate"])
    arc.proposals.approve(p["id"])             # or arc.proposals.dismiss(p["id"])
print(arc.estimate("agent", "weekly", max_credits=300))   # about what a month costs, before saving

メソッド	機能
triggers.create(source, action, when=None, limits=None, name=None, status=None)	プロジェクトの変更またはモニターの実行が条件に一致したとき、エージェントの実行、再クロール、モニターの実行、または再チェックを開始します
triggers.list(source_id=None, target_id=None) · triggers.get(id) · triggers.update(id, ...) · triggers.delete(id)	トリガーを操作します
triggers.fires(id) · triggers.preview(id)	各ソース実行が一致した内容と開始した処理（90 日間保持）；最新の実行で何が起きるかを、発火させずに確認します
proposals.list(status="proposed", run_id=None) · proposals.approve(id) · proposals.dismiss(id)	承認するとプロジェクトまたはモニターが作成されます（モニターは最初の実行がすぐに開始されます）
estimate(kind, schedule, project_id=, monitor_id=, max_pages=, max_tier=, max_credits=, month_cap=)	スケジュールに従ってクロール、検索、またはエージェントを実行した場合の月間クレジット費用を概算します。まだ実行されていない場合は upTo を返します

サブアカウント

まだ mesharc.dev では利用できません： このセクションのすべての機能には、API のフィーチャーブランチにある次の機能が必要です。

Scale または Enterprise のワークスペースでは、顧客向けのワークスペースを作成できます。それぞれに専用のキー、プロジェクト、データがあり、このワークスペースのクレジットをそれぞれの上限内で使用します。すべての呼び出しには管理者キーが必要です。

acme = arc.sub_accounts.create("Acme Ltd", monthly_cap=50_000, external_id="cust-42", idempotency_key="cust-42")
key = arc.sub_accounts.create_key(acme["id"], name="acme", scopes=["read", "write"])   # key["key"], once: for Acme

with arc.as_sub_account(acme["id"]) as acme_arc:      # your key, acting on Acme: X-MeshArc-Tenant on every request
    acme_arc.scrape("https://example.com")
arc.sub_accounts.update(acme["id"], suspended=True, reason="unpaid")   # refuses its keys, cancels what it runs

メソッド	機能
sub_accounts.list() · sub_accounts.get(id)	{data, allowed, spent, remaining} を返します。月ごとの利用状況、種類別の支出、請求、キーのアクセス権を含むサブアカウントの情報を取得します
sub_accounts.create(name, monthly_cap=None, external_id=None, idempotency_key=None) · sub_accounts.update(id, name=, monthly_cap=, suspended=, reason=)	サブアカウントを作成します。名前や上限（0：なし）を変更し、一時停止または再開します
sub_accounts.keys(id) · sub_accounts.create_key(id, ...) · sub_accounts.revoke_key(id, key_id)	顧客専用のキーを管理します
as_sub_account(id) · MeshArc(key, tenant=id)	すべてのリクエストがそのサブアカウントとして動作するクライアントを作成します

接続と保存済みログイン

mesharc.dev ではまだ利用できません： このセクションの機能には、API の機能ブランチにある以下の機能が必要です。

pdl = arc.connections.create("pdl", name="Company data", secrets={"api_key": "..."})
print(arc.connections.test(pdl["id"]))   # {status: healthy | failing, error, detail}
print(arc.logins.list()["enabled"])      # saved logins: made in the app, from a live browser

connections はワークスペースの接続先です。接続先、モデル、データプロバイダーを扱い、providers()、list()、create(provider, name=, config=, secrets=)、get(id)、update(id, ...)、delete(id)、test(id) を利用できます。シークレットは送信されますが、返されることはありません。logins では、ワークスペースに保存されているログイン情報を一覧表示する list() と、ログイン情報を更新する update(id, name=, expired=)、テストする test(id)、削除する delete(id) を利用できます。ログイン情報は、実行中のブラウザーからアプリに保存されます。セッションが返されることはありません。どちらも管理者キーが必要です。

サイトの監視：プロジェクトと実行

project = arc.projects.create(
    "https://docs.example.com",
    name="Docs",
    schedule="weekly",                                        # manual | hourly | daily | weekly
    config={"max_pages": 300, "include_paths": ["/docs/*"]},
)

run = arc.runs.start(project["id"], wait=True)                # the first run
# ...a week later, or arc.runs.start again: the second run produces the change record

record = arc.changes(project["id"])
print(record["change"]["counts"])   # {'added': …, 'removed': …, 'modified': …, 'withheld': …}

diff = arc.page_diff(project["id"], "https://docs.example.com/pricing")

メソッド	機能
projects.list() · projects.get(id) · projects.update(id, name=, schedule=, retention=, config=) · projects.delete(id)	プロジェクト
runs.list(project_id) · runs.start(project_id, wait=) · runs.wait(project_id, run_id) · runs.get(project_id, run_id) · runs.cancel(project_id, run_id)	実行
pages(project_id, run_id=None) · page(project_id, url, run_id=None)	実行のページ一覧、または1ページの全内容
changes(project_id, run_id=None) · page_diff(project_id, url, run_id=None)	変更記録、または1ページの単語単位の差分
search(project_id, q, mode="content" | "selector", run_id=None)	この語句（「フレーズ」も指定可能）が記載されているページ、またはこのセレクター（CSS／XPath）を含むページ
recrawl(project_id, urls)	指定したページを今すぐ再取得
sources(project_id)	シード、サイトマップ、URL リスト、フィード、パターン、および前回の実行でそれぞれから見つかった内容
export(project_id, path, dataset="pages", fmt="jsonl", run_id=None, urls=None)	データセット（pages、markdown、changes、fields、sitemap）を jsonl または csv 形式でファイルにストリーミング出力

arc.export(project["id"], "pages.csv", dataset="pages", fmt="csv")

ワークスペース

me = arc.me()               # the workspace, its plan and limits, credits used and remaining, what this key may do
usage = arc.usage()         # pages per day, this month by engine
queue = arc.monitor()       # the job queue: what is queued and running (not arc.monitors)
meta = arc.meta()           # verdict meanings, engine costs, the config defaults
keys = arc.keys()
key = arc.create_key("ci", scopes=["read", "write"], projects=[project["id"]], expires_in_days=90)   # key["key"], once
arc.revoke_key(key["id"])

エラー

すべての失敗で MeshArcError が発生します。

from mesharc import MeshArc, MeshArcError

try:
    arc.crawl("https://example.com", limit=1_000_000)
except MeshArcError as exc:
    print(exc.status, exc.code, exc.detail, exc.request_id)

code	ステータス	意味
validation	400 / 422	リクエストに誤りがあります。内容は detail に記載されています
unauthorized	401	キーがないか、取り消し済みまたは期限切れです
plan_limit	402	プランに含まれていないか、クレジットを使い切っています
forbidden	403	キーのスコープでは許可されていません
not_found	404	該当するものがないか、このキーでは表示できません
conflict	409	リクエストが現在の状態と矛盾しています
expired	410	エージェントの実行が保存期限（7日間）を過ぎています
rate_limited	429	キーのレート制限を超えています。再試行可能な時刻は X-RateLimit-Reset に記載されています
internal	500	サポートへの問い合わせ時に request_id を伝えてください

request_id は、API がレスポンスと独自のログに付与する ID です。サポートへの問い合わせは、この文字列を伝えるところから始められます。

ほかに2つのケースがあります。ネットワーク障害、または timeout に達したリクエストでは、status == 0 かつ code が network または timeout の MeshArcError が発生します。クライアントが待機を中止したジョブでは MeshArcTimeoutError が発生します。これは MeshArcError と TimeoutError の両方であり、後からポーリングできるように job_id を保持します（arc.get_crawl(id)、arc.batch(id)、arc.get_search(id)、arc.get_agent(id)）。

冪等性とタイムアウト

• scrape、scrape_one、crawl、web_search、agent、AgentRun.continue_、AgentRun.follow_up、monitors.create、monitors.run、agent_batches.start、sub_accounts.create は idempotency_key= を受け取ります。同じキーを24時間以内に再送すると、2つ目のジョブではなく最初の結果が返ります。MCP サーバーの search_web ツールは、意図的にキーを送信しません。完了した検索から1時間以内に同じ検索を行うと、いずれにしてもキャッシュから結果が返るためです。run_agent、continue_agent、create_monitor ツールは、入力と10分間の時間枠から作成した独自のキーを送信するため、同じ10分間内の再試行は同じ実行にまとめられ、それ以降に再実行すると新しい実行になります。
• 待機を伴う呼び出しでは、ポーリング間隔（秒）を指定する poll= と、TimeoutError が発生するまでの秒数を指定する timeout= を受け取ります。また、ほとんどの呼び出しは wait= を受け取ります。wait=False を指定すると、結果を含むエンベロープがすぐに返ります。デフォルト値は異なります。scrape、batch、crawl（および Crawl.wait、Crawl.pages）、runs.start／runs.wait は3秒ごとに、最長1時間ポーリングします。scrape_one と web_search は2秒ごとに、最長10分ポーリングします。map／map_details と extract は2秒ごとに、最長5分ポーリングします。AgentRun.wait と AgentRun.trace は2秒ごとに、最長1時間ポーリングします。
• 単一ページのスクレイプにおける timeout_s は、API がリクエストを開いたままにする時間です（デフォルトは60秒、最長120秒）。それより時間がかかるページはIDが返され、ポーリングで結果を取得します。
• MeshArc(..., timeout=150.0) は、リクエストごとのHTTPタイムアウトです。安全に再実行できる場合、すなわち GET、DELETE、または冪等性キーを指定した POST の場合、429、502、503、504、およびネットワーク障害が発生すると、max_retries 回（デフォルトは2回）まで、Retry-After を尊重して再試行します。

クレジット

すべての応答には利用料金が記載されます。ページには credits、ジョブのエンベロープには creditsUsed、HTTP応答には X-MeshArc-Credits が含まれます。ページの料金は読み取りに使用したエンジンに応じて決まり、通常の取得は1、レンダリングは4です。拒否されたページや404には料金がかかりません。ウェブ検索の結果ページの料金は読み取りに使用したエンジンに応じて決まり、すべてのエンジンが拒否した場合は料金がかかりません。完了した検索と同じ検索（クエリ、ニュースまたはウェブ、結果ページ、国、言語、新しさ、ドメインが同一）を1時間以内（ニュースの場合は10分以内）に行うと、キャッシュから結果が返り、結果ページの料金はかかりません。一方、スクレイプ対象のページにはいずれの場合も料金がかかります。エージェントの実行では、読み取った各ページに対する料金（拒否されたページは無料）と、モデルプロバイダーの料金に20％を加えたモデルのトークン料金（ワークスペース独自の LLM 接続では1,000トークンあたり1クレジット）が発生し、max_credits（デフォルトは2,000）の範囲内で課金されます。creditsUsed には両方が計上されます。モニターの実行は、検索とエージェントの実行と同じように課金されます。スケジュールとプランについては、mesharc.dev/docs/billing をご覧ください。

MCP サーバー

このパッケージには MeshArc の MCP サーバーも含まれており、Claude Desktop、Claude Code、Cursor などの MCP クライアントから、ツールとしてスクレイプ、クロール、マップ作成、ウェブ検索、エージェントへの質問の依頼、変更記録の閲覧ができます。Python 3.10 以上が必要です。

ホスト型のサーバーもあるため、ほとんどの場合、インストールは不要です。

# Claude Code
claude mcp add --transport http mesharc https://mcp.mesharc.dev/mcp

ブラウザーが一度開き、mesharc.dev にサインインして承認すると、その後は使用できます。承認すると、アプリ専用の API キーが発行されます。このキーは「Settings」→「API keys」で確認および失効できます。変更を許可しない限り、読み取り専用です。Claude.ai や ChatGPT のコネクター、Claude モバイル、Cursor など、リモート MCP URL を受け取るクライアントは、いずれも同じ方法で接続できます。

または、独自のキーを使って、stdio 経由で自分で実行することもできます。

pip install "mesharc[mcp]"
MESHARC_API_KEY=mesharc_... mesharc-mcp          # serves over stdio

# Claude Code
claude mcp add mesharc -e MESHARC_API_KEY=mesharc_... -- mesharc-mcp

ツール：scrape_urls、map_site、crawl_site、search_web、list_projects、get_project、create_project、update_project、delete_project、start_run、list_runs、list_pages、get_changes、get_job、cancel_job、run_agent、continue_agent、create_monitor、list_monitors、pause_monitor、get_monitor_rows（最後の6つはまだ mesharc.dev で利用できません。API のエージェント機能とモニター機能が必要で、現在はその機能ブランチにあります）。create_monitor はウェブ検索またはエージェントへの質問をスケジュールに従って実行し、毎回の結果を前回と比較します。list_monitors はモニターとその実行結果を表示し、pause_monitor はモニターを一時停止・再開し、get_monitor_rows はエージェントモニターが追跡するレコードを読み取ります。create_project は max_credits_per_run と max_credits_per_month を受け取ります。get_project はプロジェクトの webhook と最近の配信結果を表示し、update_project は webhook を設定してテストを送信します（test_webhook=true）。すべてのツールはこのクライアントを通じて呼び出され、それぞれの応答は出力スキーマで定義されています。ツールが失敗すると、{error, status} を返し、API から提供された場合は code と request_id も含まれます。

ページが多数含まれる結果は、全容ではなく地図です。クロールは、読み取ったページのインデックス（最大500件。予算に余裕が必要な場合はそれより少なくなります）、最大60,000文字の予算内に収まる抜粋（最大50件）、各ページのリンク数を返しますが、リンク自体は返しません。必要なページを1つだけ取得するには、get_job(kind="crawl", id=…, url=…) を使います。または、cursor= を指定してクロールを続けます。複数URLのスクレイプが予算を超えると、残りはステータス別に集計され、正常に取得できなかったURLが示されます。ページを1つだけ指定した場合、つまり url を指定した list_pages、または単一の URL を指定した scrape_urls（すべての形式を取得するには full=true）では、最大12,000文字までページ全体が返されます。search_web の応答も同じ60,000文字の上限内に収まり、スクレイプしたページは抜粋になります。scrape_urls に full=true を指定すると、1ページを全体まで読み取ります。エージェントの応答も同様です。予算を超えると、まず fieldSources（回答の各値の出所）が省略され、次にソースが最大50件（容量の半分を超える場合はそれより少なく）に削減されます。その後で初めて data が JSON テキストに置き換えられて切り詰められ、完全な回答の場所として GET /api/v1/agent/{id}、またはこのクライアントでは get_agent(id) が案内されます。

ホスト環境では、接続を読み取り専用で承認できます。読み取り専用で知っておくべき制限は、ワークスペース全体は読み取れますが、サイトにはアクセスできないことです。データを取得する操作はすべて書き込み操作です。ワークスペースの外部にアクセスし、通常はクレジットを消費するためです。map_site はサイトのサイトマップのみを読み取りますが、サイトマップファイルごとにクレジットを消費し、ほかの取得ツールと同様に制限されます。list_projects、get_project、list_runs、list_pages、get_changes、get_job、list_monitors、get_monitor_rows は使用できます。取得または書き込みを行う13個のツール、つまり scrape_urls、map_site、crawl_site、search_web、run_agent、continue_agent、create_monitor、pause_monitor、create_project、update_project、delete_project、start_run、cancel_job は、アプリを再接続して「変更も許可する」にチェックを入れる（書き込みアクセスを許可する）まで、対処方法を示す {"code": "read_only"} を返します。delete_project には書き込みアクセスに加えて管理者 API キーが必要ですが、接続済みアプリはそのキーを保持しないため、そのようなキーを使ってローカルで実行した場合にのみ機能します。

ホスト環境では、クロール、完了まで待機するよう指定した実行、複数URLのスクレイプ、ウェブ検索など、接続を数分間開いたままにするツールは、MESHARC_MCP_WAIT 秒後にジョブを返します（デフォルトは25秒です。多くの MCP ホストでは、それより早くツール呼び出しがタイムアウトするためです）。処理はサーバー側で続行され、get_job で状況を確認し、cancel_job でクロール、実行、バッチ、エージェント実行を停止できます。スクレイプを伴う検索では、結果が返され、ページの取得が続いている場合、結果とページ取得用のジョブが返されます。ローカルで実行すると、これらのツールは従来どおり処理が終わるまで待機します。 run_agent は、開始時に指定された urls のサイト上にエージェントをとどめます。ただし、アプリと同様に allowed_domains で別の指定がある場合は除きます。エージェントが読み取ったページから、別の場所へ移動するよう指示されることがあるためです。allowed_domains=[] にすると任意のサイトを読み取れるようになり、urls がなければ、エージェントをとどめるものは何もありません（クライアントの agent() は、API の仕様どおり、渡された内容をそのまま送信します。allowed_domains を指定しなければ制限はありません）。

run_agent は、ホスト型でもローカルでも、一切待機しません。エージェントの処理には数分かかるため、実行開始後すぐに、これまでの実行で消費したクレジットとともにジョブを返します。get_job(kind="agent", id=…) でジョブを追跡します（30～60 秒ごと）。処理が完了すると、結果を返します。cancel_job(kind="agent", id=…) は次のステップに進む前に処理を停止しますが、すでに消費したクレジットはそのまま課金されます。実行は 7 日間保持され、その後 get_job は status: "expired" を返します。完了済みの実行に対するリトライでは、その結果が返されます。クレジット上限で停止した実行（status: "credit_limit"、見つかった内容は data.partial に格納されます）は、continue_agent(id=…, max_credits=…) で続行できます。続行すると、同じスレッド上で新しい実行が開始され、中断した箇所から再開します。読み取り済みのページは保持され、再度課金されることはありません。新しい実行のジョブも同じ方法で返されます。上限に達していない実行は、コード conflict で拒否されます。続行済みの実行に対して再度リクエストした場合（10 分間のキー有効期間を過ぎたリトライも含む）は、続行した実行が返され、新しい実行は開始されません。

セルフホスト

MESHARC_MCP_PUBLIC_URL=https://mcp.example.dev/mcp MESHARC_OAUTH_ISSUER=https://api.example.dev MESHARC_INTROSPECT_SECRET=...                      mesharc-mcp --http --host 127.0.0.1 --port 8040

サーバーはキーを保持しません。リクエストごとに呼び出し元の OAuth トークンが渡され、MESHARC_OAUTH_ISSUER に照らして検証された後、呼び出しに使用されます。そのため、1 つのプロセスで複数のワークスペースに対応できます。このモードでは MESHARC_API_KEY は読み取られません。設定されている場合、起動時に無視されることが通知されます。

リバースプロキシの背後で使用する場合、127.0.0.1 にバインドすると、MCP SDK はローカルホストのみを許可する Host 許可リストを用いて DNS リバインディング保護を有効にする点に注意してください。そのため、サーバーは MESHARC_MCP_PUBLIC_URL に基づいて独自の許可リストを渡します。この設定がない場合、プロキシ経由のリクエストはすべて拒否されます。ブラウザベースのクライアントを使用する場合は、MESHARC_MCP_ALLOWED_ORIGINS（カンマ区切り）で Origin 許可リストに追加してください。

プライバシーとセキュリティ

クライアントが通信するのは 1 つのホスト、つまり API のベース URL のみです。MESHARC_API_URL または base_url= で別途指定しない限り、https://api.mesharc.dev が使用されます。それ以外の場所とは通信しません。キーは HTTPS 経由で、ベアラーヘッダーとしてのみ送信されます。ディスクへの書き込みはなく、テレメトリーも送信されません。クライアントが読み取るのは MESHARC_API_KEY と MESHARC_API_URL のみです。HTTP モードの MCP サーバーは MESHARC_MCP_PUBLIC_URL、MESHARC_OAUTH_ISSUER、MESHARC_INTROSPECT_SECRET、MESHARC_MCP_WAIT、MESHARC_MCP_ALLOWED_ORIGINS を読み取り、独自のキーは持ちません。

MeshArc がユーザーとクロールしたページに関して保持する情報、およびその保持期間については、プライバシーポリシーをご覧ください。サービスのセキュリティ対策については、セキュリティページをご覧ください。このクライアントまたはサービスの脆弱性を報告する場合は、公開イシューを作成せず、[email protected] までご連絡ください。詳しくは SECURITY.md をご覧ください。

その他

クライアントは薄いラッパーです。各メソッドは API を 1 回呼び出し、API の JSON を dict として返します。全リファレンスは mesharc.dev/docs/api にあります。使い終わったら arc.close() を呼び出すか、クライアントをコンテキストマネージャーとして使用してください。

• ドキュメント：mesharc.dev/docs
• Node クライアント：npm install mesharc — mesharc-node
• イシューとプルリクエスト：mesharc-python
• お問い合わせ：[email protected]

MIT。