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

# Agent Workflow

> Use Tovuk scraper APIs safely from an automated agent.

Set JSON output once for agent sessions:

```sh theme={"dark"}
export TOVUK_OUTPUT=json
```

## Scraper Sequence

<Steps>
  <Step title="Confirm account and price">
    ```sh theme={"dark"}
    tovuk account show
    tovuk api-key list
    tovuk api-key create "Production scraper"
    tovuk api-key revoke api_key_0123456789abcdef01234567
    tovuk pricing
    tovuk usage
    tovuk billing checkout plus
    tovuk billing portal
    ```

    Inspect balance, `priceEvents[].usdMicros`, and
    `usage.billingEstimate.lineItems` before high-count Requests.
  </Step>

  <Step title="Inspect scraper availability">
    ```sh theme={"dark"}
    tovuk scraper list
    tovuk scraper health
    tovuk scraper show tiktok
    ```
  </Step>

  <Step title="Create paid public-data work">
    ```sh theme={"dark"}
    tovuk request create tiktok '{"operation":"search","query":"rust programming","limit":100}'
    tovuk request create github '{"operation":"codeSearch","query":"serde language:Rust","maxRepos":3,"limit":100}'
    tovuk request create linkedin '{"operation":"post-search","query":"b2b sales","sort_type":"date_posted","author_company_urns":"1035","limit":50}'
    tovuk request create google-maps '{"searchTerms":["coffee shops"],"locationQuery":"Seattle, WA","limit":25}'
    tovuk request create amazon '{"operation":"search","query":"mechanical keyboard","limit":25}'
    ```
  </Step>

  <Step title="Poll and read results">
    ```sh theme={"dark"}
    tovuk request show request_123
    tovuk request results request_123 --limit 1000
    ```

    Use `--cursor <nextCursor>` with `tovuk request list` and `tovuk request results`
    to continue request and stored-result pagination.
    For ecommerce Records, inspect `featureCoverage` to see whether requested
    Apify-style fields were extracted, absent, partially extracted, or accepted
    for compatibility. Public metadata fields can include `tags`, `keywords`,
    `questionSamples`, `customerPhotoUrls`, `minimumOrderQuantity`, `rfqText`,
    `resultPosition`, and `adPosition`.
  </Step>

  <Step title="Cancel when needed">
    ```sh theme={"dark"}
    tovuk request cancel request_123
    ```
  </Step>
</Steps>

## Public-Data Rule

Scraper Requests are for public data only. Do not send cookies, passwords,
account tokens, private session data, private account content, private
repository credentials, or proxy URLs.

## Support

Open support tickets only after capturing the request id, exact command, and
first actionable error:

```sh theme={"dark"}
tovuk support list --limit 20
tovuk support create "Request failed" "Request failed after retry." --request-id request_123 --scraper-id tiktok --failing-command "tovuk request show request_123" --first-log-line "upstream timeout" --severity normal
tovuk support resolve ticket_0123456789abcdef0123
```

AI/API agents can also call `POST /v1/support/tickets` directly with an account
API key or session bearer token. Support tickets are account-scoped service
tickets between the authenticated account and Tovuk for scraper, billing, API
key, and account help. Ticket responses include `created_by` so later agents can
see whether the ticket came from an account session or account API key.