> ## Documentation Index > Fetch the complete documentation index at: https://docs.justpaid.io/llms.txt > Use this file to discover all available pages before exploring further. # Get Items > ### Retrieve Usage-Based Billable Items Fetch a list of usage-based billable items, optionally filtered by a specific customer ID or external customer ID. #### Overview This endpoint allows you to retrieve billable items along with associated customer details from the database. You can filter the results by either a customer ID or external customer ID. If no filter is provided, the endpoint returns billable items for all customers. #### Parameters - **customer_id** (optional): The unique identifier of the customer to filter events by. - **external_customer_id** (optional): The external identifier of the customer to filter events by. ## OpenAPI ````yaml get /api/v1/usage/items openapi: 3.1.0 info: title: NinjaAPI version: 1.0.0 description: '' servers: - url: https://api.justpaid.io security: [] paths: /api/v1/usage/items: get: summary: Get Items description: >- ### Retrieve Usage-Based Billable Items Fetch a list of usage-based billable items, optionally filtered by a specific customer ID or external customer ID. #### Overview This endpoint allows you to retrieve billable items along with associated customer details from the database. You can filter the results by either a customer ID or external customer ID. If no filter is provided, the endpoint returns billable items for all customers. #### Parameters - **customer_id** (optional): The unique identifier of the customer to filter events by. - **external_customer_id** (optional): The external identifier of the customer to filter events by. operationId: loopfour_backend_external_api_usage_get_items parameters: - in: query name: customer_id schema: title: Customer Id type: string required: false - in: query name: external_customer_id schema: title: External Customer Id type: string required: false responses: '200': description: A list of customers with their associated events content: application/json: schema: items: $ref: '#/components/schemas/ItemListSchema' title: Response type: array examples: example1: summary: Single customer with one event value: - customer_id: 9f8b47e4-1aad-4f08-b1e3-d9e4b4b85e8f external_customer_id: ext789 customer_name: John Doe customer_email: john.doe@example.com items: - item_id: 123e4567-e89b-12d3-a456-426614174000 item_name: gpt4o_input_tokens_used billing_alias: gpt4o_input_tokens_used example2: summary: Multiple customers with multiple events value: - customer_id: 9f8b47e4-1aad-4f08-b1e3-d9e4b4b85e8f external_customer_id: ext789 customer_name: John Doe customer_email: john.doe@example.com items: - item_id: 123e4567-e89b-12d3-a456-426614174000 item_name: gpt4o_input_tokens_used billing_alias: gpt4o_input_tokens_used - item_id: 223e4567-e89b-12d3-a456-426614174000 item_name: claud_sonnet3.5_input_tokens_used billing_alias: claud_sonnet3.5_input_tokens_used - customer_id: c8b47e4-1aad-4f08-b1e3-d9e4b4b85e8f external_customer_id: ext456 customer_name: Jane Smith customer_email: jane.smith@example.com items: - item_id: 323e4567-e89b-12d3-a456-426614174000 item_name: images_processed billing_alias: images_processed security: - HttpBearerAuth: [] components: schemas: ItemListSchema: description: |- Schema for a list of usage based items associated with a customer. Attributes: customer_id (str): Unique identifier for the customer. external_customer_id (Optional[str]): An optional external identifier for the customer. customer_name (Optional[str]): The name of the customer. Optional. customer_email (Optional[str]): The email address of the customer. Optional. items (List[ItemSchema]): A list of usage based item associated with the customer. properties: customer_id: description: The unique identifier for the customer. example: 9f8b47e4-1aad-4f08-b1e3-d9e4b4b85e8f title: Customer Id type: string external_customer_id: anyOf: - type: string - type: 'null' description: An external identifier for the customer mapped by external systems. example: ext789 title: External Customer Id customer_name: anyOf: - type: string - type: 'null' description: >- The name of the customer. This field is optional and can be used for display purposes. example: John Doe title: Customer Name customer_email: anyOf: - type: string - type: 'null' description: >- The email address of the customer. Optional and can be used for communication. example: john.doe@example.com title: Customer Email items: default: [] description: >- A list of events associated with the customer. Each event is represented by an event_id and event_name. items: $ref: '#/components/schemas/ItemSchema' title: Items type: array required: - customer_id title: ItemListSchema type: object ItemSchema: description: |- Schema for an individual item. Attributes: item_id (str): Unique identifier for the item. item_name (str): Name of the item. properties: item_id: description: The unique identifier for the item. example: 123e4567-e89b-12d3-a456-426614174000 title: Item Id type: string item_name: description: >- The name of the item, typically describing what the billable item is about. This field is mapped to the plan_item name so that when a new usage item is ingested the system will automatically map it the plan line item. example: gpt4o_input_tokens_used title: Item Name type: string billing_alias: anyOf: - type: string - type: 'null' description: >- The billing alias of the item, typically describing what the billable item is about. This field is mapped to the plan_item billing_alias so that when a new usage item is ingested the system will automatically map it the plan line item. example: gpt4o_input_tokens_used title: Billing Alias required: - item_id - item_name title: ItemSchema type: object securitySchemes: HttpBearerAuth: type: http scheme: bearer ````