---
title: "Fetch cost traces for an organization"
method: GET
path: "/traces"
tags: ["traces"]
---

# Fetch cost traces for an organization

`GET /traces`

## Request

- Base URL: `https://api.agentpaid.io/api/v1`
- URL: `https://api.agentpaid.io/api/v1/traces`
- Auth: HTTP bearer

## Query parameters

- `limit` integer
- `offset` integer
- `startTime` string, date-time
- `endTime` string, date-time
- `externalCustomerId` string
- `externalProductId` string
- `externalAgentId` string
- `metadata` string

## Response `200`

Success response

- TracesResponse: Response containing cost traces and pagination metadata
  - `traces` Trace[], required
    - `name` string, required: The name/type of the operation (e.g., "trace.openai.agents.on_agent")
    - `vendor` string, required: The vendor/provider (e.g., "openai", "anthropic", "mistral")
    - `model` string, required: The model used for the operation (e.g., "gpt-4o-mini", "claude-3-sonnet")
    - `cost` CostAmount, required: Cost amount with currency
      - `amount` number, double, required: The cost amount
      - `currency` string, required: The currency code (e.g., "USD")
    - `startTimeUnixNano` string, required: Unix timestamp in nanoseconds when the operation started
    - `endTimeUnixNano` string, required: Unix timestamp in nanoseconds when the operation completed
    - `attributes` object, required: Additional metadata about the trace (e.g., tokens, etc.)
    - `customerId` string: The internal customer ID associated with this trace
    - `externalCustomerId` string, nullable: Your system's customer ID associated with this trace
    - `productId` string, nullable: The product ID associated with this trace
    - `externalProductId` string, nullable: Your system's product ID associated with this trace
    - `agentId` string, nullable: DEPRECATED: Use productId instead. The product/agent ID associated with this trace.
    - `externalAgentId` string, nullable: DEPRECATED: Use externalProductId instead. Your system's agent/product ID.
  - `meta` PaginationMeta, required: Pagination metadata for cost traces
    - `limit` integer, required: The requested limit
    - `offset` integer, required: The requested offset
    - `count` integer, required: Number of items returned in this response
    - `hasMore` boolean, required: Whether there are more results available
    - `startTime` string, date-time: The startTime filter that was applied (if any)
    - `endTime` string, date-time: The endTime filter that was applied (if any)
    - `externalCustomerId` string: The externalCustomerId filter that was applied (if any)
    - `externalProductId` string: The externalProductId filter that was applied (if any)
    - `externalAgentId` string: DEPRECATED: Use externalProductId instead. The externalAgentId filter that was applied (if any)
    - `metadata` string: The metadata filter that was applied (if any)

## Other responses

- `400`: Bad request - Invalid query parameters
- `403`: Forbidden - Invalid or missing API key

---

[API](https://skmtc.dev/paid/apis/paid-2.md) - [All operations](https://skmtc.dev/paid/apis/paid-2/llms.txt) - [OpenAPI document](https://skmtc.dev/paid/apis/paid-2/revisions/dbdf4a60ed27?raw)