Getting started with the Grep API

Last updated: May 4, 2026

Getting started with the Grep API

The Grep API lets eligible customers start research tasks programmatically, check task status, and retrieve completed results from their own tools and workflows.

Who can use the API

API access is included with eligible subscription plans. If you do not see API settings in your account, check Settings → Billing → Plans or contact support.

Create an API key

  1. Open Settings.
  2. Go to API keys.
  3. Click Create key.
  4. Copy the key and store it securely.

For security, Grep may only show the full key once. If you lose it, create a new key and revoke the old one.

Keep your key secure

  • Do not share API keys in chat, email, or screenshots.
  • Do not commit keys to source control.
  • Store keys in a secrets manager or environment variable.
  • Rotate keys if someone leaves your team or a key may have been exposed.

Start a research task

Send a research question and choose a depth. The API returns a task identifier you can use to check progress.

At a high level, your integration should:

  1. Send the research question, selected depth, and any metadata your workflow needs.
  2. Save the returned task ID.
  3. Poll for task status until the task reaches a final state.
  4. Retrieve and store the completed result.

Check task status

Research tasks can take time, especially at higher depths. Poll the task status endpoint until the task is complete, then retrieve the result.

Recommended polling pattern:

  • Poll every few seconds at first.
  • Back off for longer-running tasks.
  • Stop polling after the task reaches a final state.
  • Handle failures and timeouts gracefully.

Choose the right depth

Use the same depths available in the Grep app:

Depth Best for
Low effort Fast, narrow questions
Deep Most business research
Ultra deep Complex or high-stakes investigations

Higher depths have higher starting reservations and may take longer to complete.

Billing for API usage

API tasks use the same billing model as tasks started in the Grep app. Grep reserves a minimum amount when a task starts, then reconciles to the real final cost based on actual token usage after the task completes.

Best practices

  • Use idempotency keys or your own request IDs when retrying task creation.
  • Store the returned task ID with your internal workflow record.
  • Avoid creating duplicate tasks on network retries.
  • Log final task status and cost for reconciliation.
  • Start with Deep unless you know the task is simple or requires Ultra deep.

Related articles