{"openapi":"3.1.0","info":{"title":"Helicone (BYOK) API","version":"0.1.0","description":"Helicone (BYOK) lets an AI assistant read your own Helicone data through the Helicone API with a key you supply (API key). Read-only: 8 tools (query_requests, count_requests, query_users, query_sessions, list_properties, list_prompts, count_prompts, list_webhooks). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it is only ever sent to...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-helicone.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-helicone/docs"},"termsOfService":"https://connectorbay.com/byok-helicone/terms"},"servers":[{"url":"https://byok-helicone.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-helicone/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/query_requests":{"post":{"operationId":"query_requests","summary":"List logged LLM requests, newest first, with model, provider, status, token counts, cost in USD, latency, user and custo","description":"List logged LLM requests, newest first, with model, provider, status, token counts, cost in USD, latency, user and custom properties (prompt and response bodies are left out). Use for \"What were my most recent LLM requests in Helicone and what did they cost\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many rows to skip, for paging.","title":"Offset"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many rows to return (1 to 100).","title":"Limit"},"sort":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"desc","description":"Sort by request time: desc (newest first) or asc.","title":"Sort"}},"title":"query_requestsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/count_requests":{"post":{"operationId":"count_requests","summary":"Count all logged LLM requests in the Helicone account. Use for \"How many LLM requests has Helicone logged in total\".","description":"Count all logged LLM requests in the Helicone account. Use for \"How many LLM requests has Helicone logged in total\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"count_requestsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/query_users":{"post":{"operationId":"query_users","summary":"List the end users that made requests in a time window with request count, prompt and completion tokens and cost. Use fo","description":"List the end users that made requests in a time window with request count, prompt and completion tokens and cost. Use for \"Which users cost me the most in Helicone this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start":{"description":"Window start as a Unix timestamp in seconds.","maximum":4102444800,"minimum":0,"title":"Start","type":"integer"},"end":{"description":"Window end as a Unix timestamp in seconds.","maximum":4102444800,"minimum":0,"title":"End","type":"integer"}},"required":["start","end"],"title":"query_usersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/query_sessions":{"post":{"operationId":"query_sessions","summary":"List sessions (grouped traces) in a time window with name, request count, tokens, cost and average latency. Use for \"Sho","description":"List sessions (grouped traces) in a time window with name, request count, tokens, cost and average latency. Use for \"Show my Helicone sessions from the last day\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_ms":{"description":"Window start as a Unix timestamp in milliseconds.","maximum":4102444800000,"minimum":0,"title":"Start Ms","type":"integer"},"end_ms":{"description":"Window end as a Unix timestamp in milliseconds.","maximum":4102444800000,"minimum":0,"title":"End Ms","type":"integer"},"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":"","description":"Only sessions whose name matches this text (empty for all).","title":"Search"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many rows to skip, for paging.","title":"Offset"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many rows to return (1 to 100).","title":"Limit"}},"required":["start_ms","end_ms"],"title":"query_sessionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_properties":{"post":{"operationId":"list_properties","summary":"List the custom property names attached to requests (for example Environment or Feature). Use for \"Which custom properti","description":"List the custom property names attached to requests (for example Environment or Feature). Use for \"Which custom properties do I track in Helicone\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_propertiesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_prompts":{"post":{"operationId":"list_prompts","summary":"List saved prompts with name, tags and creation time, one page at a time. Use for \"Which prompts are saved in Helicone\".","description":"List saved prompts with name, tags and creation time, one page at a time. Use for \"Which prompts are saved in Helicone\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":10000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number, starting at 0.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many prompts per page (1 to 100).","title":"Page Size"},"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":"","description":"Only prompts whose name matches this text (empty for all).","title":"Search"}},"title":"list_promptsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/count_prompts":{"post":{"operationId":"count_prompts","summary":"Count the saved prompts. Use for \"How many prompts do I have in Helicone\".","description":"Count the saved prompts. Use for \"How many prompts do I have in Helicone\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"count_promptsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_webhooks":{"post":{"operationId":"list_webhooks","summary":"List configured webhooks with destination, version and creation time (the signing key is not returned). Use for \"Which H","description":"List configured webhooks with destination, version and creation time (the signing key is not returned). Use for \"Which Helicone webhooks are configured\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_webhooksArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}