> ## Documentation Index
> Fetch the complete documentation index at: https://dev.jolts.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Your first company search

> Ask a question, retrieve a company list, and inspect the evidence.

You will submit a search, then retrieve the results. You need an API key and an active or trialing
subscription. [Set up authentication](/authentication) first.

## Choose how to connect

If you want to ask an AI assistant questions rather than write code, start with
[Connect your agent](/mcp-overview). The tutorial below is for developers and uses Bash with cURL.

The [API Reference](/api-reference/companies/search-companies) has a language selector above every
request example. All languages call the same endpoints and receive the same JSON; there is no
separate Jolts SDK to install.

| Example    | What you need                                                                                      |
| ---------- | -------------------------------------------------------------------------------------------------- |
| cURL       | A terminal with cURL; this tutorial's prompts use Bash                                             |
| Python     | Python and the `requests` package                                                                  |
| JavaScript | A server-side runtime with `fetch`; never expose your key in browser code                          |
| Ruby       | Ruby with `net/http` and `uri`, used by the generated example                                      |
| PHP        | PHP with the cURL extension enabled                                                                |
| Go         | Go and the standard-library packages imported by the example                                       |
| Java       | A Java project with the Unirest HTTP client; the generated snippet belongs inside your application |

Replace `<token>` with your secret **at runtime**, not in committed source. Replace
`<idempotency-key>` with a unique identifier for intentional new work. Reuse it only when retrying
the same operation. Generated snippets demonstrate one request; your application still needs to
check the status, parse the response, handle errors, and poll a pending operation as shown below.

## Make your first request

<Steps>
  <Step title="Set your connection">
    Run these commands in Bash. Enter the application origin from your account's address bar, without
    a trailing slash, then paste your key at the hidden prompt. The docs site is not the API host.

    ```bash theme={null}
    read -r -p "Application origin: " API_BASE
    read -r -s -p "API key: " API_KEY
    printf '\n'
    export API_BASE API_KEY
    ```
  </Step>

  <Step title="Find companies">
    This example looks for evidence relevant to someone selling charging equipment. Change the query
    to describe the companies and activity you want to research.

    ```bash theme={null}
    curl --fail-with-body "$API_BASE/api/companies/search" \
      -H "Authorization: Bearer $API_KEY" \
      -H "Idempotency-Key: first-company-search" \
      -H "Content-Type: application/json" \
      -d '{"query":"Companies seeking charging equipment","filters":{"countries":["CA","US"]},"limit":10,"background":true}'
    ```

    HTTP `202` means the search was accepted, not completed. Copy `usage.id` from the response.
    An identical retry can return `200` if the search has already finished.
  </Step>

  <Step title="Read the result">
    Enter the returned ID, then retrieve the operation:

    ```bash theme={null}
    read -r -p "Usage ID: " USAGE_ID
    curl --fail-with-body "$API_BASE/api/usages/$USAGE_ID" \
      -H "Authorization: Bearer $API_KEY"
    ```

    If the response is still `202`, wait a few seconds before polling again. On success, inspect
    `companies`, each company's `observations`, and their `evidence`. A completed empty list is valid.
    If `error` is present, read its code instead of treating it as an empty result.
  </Step>
</Steps>

## What you built

One company search with a reusable operation ID. Polling or retrying identical inputs with the same
key does not start another search. A new search or next page needs a **new** idempotency key.

<CardGroup cols={2}>
  <Card title="Filter and paginate" href="/workflows" icon="filter">Exclude customers you already know and inspect individual companies.</Card>
  <Card title="Read the evidence" href="/evidence" icon="file-lines">Understand facts, possible demand, confidence, and coverage.</Card>
</CardGroup>

## Troubleshooting

| Response               | What to do                                                                            |
| ---------------------- | ------------------------------------------------------------------------------------- |
| `401`                  | Check your bearer key. A revoked key cannot be reused.                                |
| `402`                  | Check that your subscription is active or trialing.                                   |
| `422`                  | Read `error.code`. Correct invalid inputs; do not retry them unchanged.               |
| `429`                  | Read `error.retry_at` when supplied and check `/api/usage`. Do not loop on the limit. |
| `planning_unavailable` | The search could not be prepared. The same key replays that terminal outcome.         |
| `idempotency_conflict` | The key belongs to different inputs. Use a new key for new work.                      |

After a terminal failure or expiration, use a new key only when you intend to start another operation.
For help, share the usage ID and error code, **never your API key**.