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

# Trace Tools with cURL

> Send a completed external operation to Planck's manual logging endpoint.

Use manual logging when an operation did not pass through the Planck AI
Gateway—for example, an external API, database query, or custom tool call. Send
one log after the operation completes.

## Production canary

This request records a synthetic tool operation. It does not call a model or a
third-party service.

```bash theme={null}
export PLANCK_API_KEY="sk-planck-..."
export REQUEST_ID="$(uuidgen | tr '[:upper:]' '[:lower:]')"
export NOW_SECONDS="$(date +%s)"

curl --fail-with-body --request POST \
  --url https://api.inquantum.ai/custom/v1/log \
  --header "Authorization: Bearer $PLANCK_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Planck-Request-Id: $REQUEST_ID" \
  --header "Planck-Session-Id: production-manual-log-canary" \
  --header "Planck-Property-Canary: manual-log" \
  --data "{
    \"providerRequest\": {
      \"url\": \"canary://manual-log\",
      \"json\": {
        \"_type\": \"tool\",
        \"toolName\": \"production_manual_log_canary\",
        \"input\": {\"safe\": true}
      },
      \"meta\": {}
    },
    \"providerResponse\": {
      \"json\": {
        \"_type\": \"tool\",
        \"toolName\": \"production_manual_log_canary\",
        \"ok\": true
      },
      \"status\": 200,
      \"headers\": {}
    },
    \"timing\": {
      \"startTime\": $NOW_SECONDS,
      \"endTime\": $NOW_SECONDS
    },
    \"provider\": \"custom\"
  }"
```

A successful write returns HTTP 200 with the same request ID:

```json theme={null}
{ "status": "ok", "planck-id": "..." }
```

Search for `$REQUEST_ID` in the Requests dashboard. Ingestion can take a few
seconds. Repository maintainers can run the send-and-query version with:

```bash theme={null}
PLANCK_API_KEY="sk-planck-..." bash planck-gateway/scripts/test-production-manual-log.sh
```

## Endpoint and authentication

Use the endpoint for the operation's provider:

| Provider                      | Endpoint             |
| ----------------------------- | -------------------- |
| Custom tool, API, or database | `/custom/v1/log`     |
| OpenAI                        | `/oai/v1/log`        |
| Anthropic                     | `/anthropic/v1/log`  |
| Google                        | `/googleapis/v1/log` |

The base URL is `https://api.inquantum.ai`. Pass a Planck API key as
`Authorization: Bearer <key>`.

`providerRequest`, `providerResponse`, and valid authentication are required.
`timing` is optional and accepts epoch seconds, epoch milliseconds, RFC 3339
strings, or `{ seconds, milliseconds }` objects. The maximum submitted payload
is 10 MB.

## Storage behavior

Requests do not all go to S3. Metadata and ordinary request/response bodies use
the durable logging pipeline and ClickHouse. Bodies over 10 KB and inline
base64 image assets are offloaded to private object storage when it is
configured; ClickHouse retains the searchable metadata and storage reference.
Use `Planck-Omit-Request: true` or `Planck-Omit-Response: true` when a body
must not be retained.

The endpoint returns success only after the log has been accepted by a durable
sink. A non-2xx response means the log must be retried if delivery is required.