> ## 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.

<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**.