chore(docs): add new filter costs by token type docs #108
Conversation
WalkthroughAdds an optional selected_token_types query parameter to the “Get costs by property” API documentation, enabling cost filtering by specified token types. Supports several token-type values with normalization rules; total_tokens is excluded. Examples added. No response schema changes. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant C as Client
participant API as Costs API
participant S as Cost Aggregator
Note over C,API: Request: GET /costs/by-property
rect rgb(235, 245, 255)
C->>API: selected_token_types=? (optional)
alt With selected_token_types
API->>S: Fetch costs filtered by specified token types
S-->>API: Aggregated costs (filtered)
else Without selected_token_types
API->>S: Fetch costs for all token types
S-->>API: Aggregated costs (all types)
end
end
API-->>C: 200 OK with cost breakdown (unchanged schema)
Note over API: total_tokens not allowed as a filter
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
✨ Finishing Touches🧪 Generate unit tests
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
avivhalfon
changed the title
![ellipsis-dev[bot]](https://avatars.githubusercontent.com/in/64358?s=60&v=4){kind=small}
There was a problem hiding this comment.
Important
Looks good to me! 👍
Reviewed everything up to 0db0403 in 52 seconds. Click for details.
- Reviewed
31lines of code in1files - Skipped
0files when reviewing. - Skipped posting
2draft comments. View those below. - Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.
1. api-reference/costs/property_costs.mdx:27
- Draft comment:
Ensure the inline JSX 'NEW' badge style renders correctly in MDX. - Reason this comment was not posted:
Confidence changes required:33%<= threshold50%None
2. api-reference/costs/property_costs.mdx:29
- Draft comment:
Docs are clear; consider adding explicit details on token normalization for non-standard types. - Reason this comment was not posted:
Confidence changes required:33%<= threshold50%None
Workflow ID: wflow_IySzW12y27F7cx1X
You can customize 
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (5)
api-reference/costs/property_costs.mdx (5)
26-44: Clarify filter semantics and aggregation scope.State explicitly that the filter sums the selected token types (union) and that all returned costs (including total_cost) reflect only those selected types. This prevents readers from assuming per-type breakdowns.
<ParamField query="selected_token_types" type="string"> - <span style={{backgroundColor: '#10b981', color: 'white', padding: '2px 6px', borderRadius: '4px', fontSize: '12px', fontWeight: 'bold'}}>NEW</span> Filter costs by specific token types. Separate multiple types with commas. + <span style={{backgroundColor: '#10b981', color: 'white', padding: '2px 6px', borderRadius: '4px', fontSize: '12px', fontWeight: 'bold'}}>NEW</span> Filter costs by specific token types. Separate multiple types with commas (CSV). + + Costs are aggregated across the selected types (union). The response schema is unchanged; all cost figures (including "total_cost") reflect only the selected token types.
29-35: Define normalization details (case/whitespace) to avoid client-side ambiguity.Readers need to know if values are case-insensitive and whether spaces around commas are accepted.
**Supported token types:** - `input_tokens` or `prompt_tokens` (automatically normalized to `prompt_tokens`) - `output_tokens` or `completion_tokens` (automatically normalized to `completion_tokens`) - `cache_read_input_tokens` - `cache_creation_input_tokens` - Other token types as they appear in your data + + Matching is case-insensitive and surrounding whitespace is ignored (e.g., `prompt_tokens, completion_tokens` is valid).
36-44: Document behavior for unsupported values, includingtotal_tokens.Specify whether the API rejects the request (preferred: 400 with details) or ignores invalid values. This affects client error handling.
**Note:** `total_tokens` cannot be used as a filter. + + If an unsupported value (including `total_tokens`) is provided, the API returns a 400 Bad Request with an error message listing allowed values. + (Confirm actual behavior and adjust this note accordingly.)
27-27: Prefer a reusable Badge component over inline styles.If the docs site provides a Badge/Label component, use it for consistency and theming.
- <span style={{backgroundColor: '#10b981', color: 'white', padding: '2px 6px', borderRadius: '4px', fontSize: '12px', fontWeight: 'bold'}}>NEW</span> Filter costs by specific token types. Separate multiple types with commas. + <Badge color="green">NEW</Badge> Filter costs by specific token types. Separate multiple types with commas.If no Badge component exists, ignore this suggestion.
38-44: Add a concrete curl example showing CSV usage and URL encoding.A real request helps users copy/paste and reduces mistakes.
**Examples:** - `selected_token_types=input_tokens,output_tokens` - `selected_token_types=prompt_tokens,cache_read_input_tokens` - `selected_token_types=completion_tokens` When this parameter is omitted, costs for all token types are included. + + Example request: + ```bash + curl -G 'https://api.traceloop.com/api/v2/costs/by-association-property' \ + --data-urlencode 'property_name=session_id' \ + --data-urlencode 'start_time=2025-04-15T00:00:00Z' \ + --data-urlencode 'end_time=2025-04-28T23:00:00Z' \ + --data-urlencode 'selected_token_types=prompt_tokens,completion_tokens' + ```
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
api-reference/costs/property_costs.mdx(1 hunks)
Important
Adds
selected_token_typesparameter to filter costs by token types inproperty_costs.mdx.selected_token_typesparameter to filter costs by token types inproperty_costs.mdx.input_tokens,output_tokens,cache_read_input_tokens,cache_creation_input_tokens, and others.total_tokenscannot be used as a filter.This description was created by
for 0db0403. You can customize this summary. It will automatically update as commits are pushed.
Summary by CodeRabbit