How to use the Usage API and Cost API to monitor your OpenAI usage

# Set up the API key and headers
OPENAI_ADMIN_KEY = '<PLACEHOLDER>'  

headers = {
    "Authorization": f"Bearer {OPENAI_ADMIN_KEY}",
    "Content-Type": "application/json"
}

# Define the API endpoint
url = "https://api.openai.com/v1/organization/usage/completions"

# Calculate start time: n days ago from now
days_ago = 30
start_time = int(time.time()) - (days_ago * 24 * 60 * 60)

# Define parameters with placeholders for all possible options
params = {
    "start_time": start_time,  # Required: Start time (Unix seconds)
    # "end_time": end_time,  # Optional: End time (Unix seconds)
    "bucket_width": "1d",      # Optional: '1m', '1h', or '1d' (default '1d')
    # "project_ids": ["proj_example"],  # Optional: List of project IDs
    # "user_ids": ["user_example"],     # Optional: List of user IDs
    # "api_key_ids": ["key_example"],   # Optional: List of API key IDs
    # "models": ["gpt-4o-mini-2024-07-18"],  # Optional: List of models
    # "batch": False,             # Optional: True for batch jobs, False for non-batch
    # "group_by": ["model"],     # Optional: Fields to group by
    "limit": 7,                 # Optional: Number of buckets to return, this will chunk the data into 7 buckets
    # "page": "cursor_string"   # Optional: Cursor for pagination
}

# Initialize an empty list to store all data
all_data = []

# Initialize pagination cursor
page_cursor = None

# Loop to handle pagination
while True:
    if page_cursor:
        params["page"] = page_cursor

    response = requests.get(url, headers=headers, params=params)

    if response.status_code == 200:
        data_json = response.json()
        all_data.extend(data_json.get("data", [])) 

        page_cursor = data_json.get("next_page")
        if not page_cursor:
            break  
    else:
        print(f"Error: {response.status_code}")
        break  

if all_data:
    print("Data retrieved successfully!")
else:
    print("Issue: No data available to retrieve.")

print(json.dumps(all_data, indent=2))

# Initialize a list to hold parsed records
records = []

# Iterate through the data to extract bucketed data
for bucket in all_data:  
    start_time = bucket.get("start_time")
    end_time = bucket.get("end_time")
    for result in bucket.get("results", []):
        records.append({
            "start_time": start_time,
            "end_time": end_time,
            "input_tokens": result.get("input_tokens", 0),
            "output_tokens": result.get("output_tokens", 0),
            "input_cached_tokens": result.get("input_cached_tokens", 0),
            "input_audio_tokens": result.get("input_audio_tokens", 0),
            "output_audio_tokens": result.get("output_audio_tokens", 0),
            "num_model_requests": result.get("num_model_requests", 0),
            "project_id": result.get("project_id"),
            "user_id": result.get("user_id"),
            "api_key_id": result.get("api_key_id"),
            "model": result.get("model"),
            "batch": result.get("batch"),
            "service_tier": result.get("service_tier")
        })

# Create a DataFrame from the records
df = pd.DataFrame(records)

# Convert Unix timestamps to datetime for readability
df['start_datetime'] = pd.to_datetime(df['start_time'], unit='s')
df['end_datetime'] = pd.to_datetime(df['end_time'], unit='s')

# Reorder columns for better readability
df = df[
    [
        "start_datetime", "end_datetime", "start_time", "end_time",
        "input_tokens", "output_tokens", "input_cached_tokens",
        "input_audio_tokens", "output_audio_tokens", "num_model_requests",
        "project_id", "user_id", "api_key_id", "model", "batch", "service_tier"
    ]
]

# Display the DataFrame
df.head()

if not df.empty:
    plt.figure(figsize=(12, 6))
    
    # Create bar charts for input and output tokens
    width = 0.35  # width of the bars
    indices = range(len(df))
    
    plt.bar(indices, df['input_tokens'], width=width, label='Input Tokens', alpha=0.7)
    plt.bar([i + width for i in indices], df['output_tokens'], width=width, label='Output Tokens', alpha=0.7)
    
    # Set labels and ticks
    plt.xlabel('Time Bucket')
    plt.ylabel('Number of Tokens')
    plt.title('Daily Input vs Output Token Usage Last 30 Days')
    plt.xticks([i + width/2 for i in indices], [dt.strftime('%Y-%m-%d') for dt in df['start_datetime']], rotation=45)
    plt.legend()
    plt.tight_layout()
    plt.show()
else:
    print("No data available to plot.")

# Calculate start time: n days ago from now
days_ago = 30
start_time = int(time.time()) - (days_ago * 24 * 60 * 60)

# Define parameters with grouping by model and project_id
params = {
    "start_time": start_time,         # Required: Start time (Unix seconds)
    "bucket_width": "1d",            # Optional: '1m', '1h', or '1d' (default '1d')
    "group_by": ["model", "project_id"],  # Group data by model and project_id
    "limit": 7                       # Optional: Number of buckets to return
}

# Initialize an empty list to store all data
all_group_data = []

# Initialize pagination cursor
page_cursor = None

# Loop to handle pagination
while True:
    if page_cursor:
        params["page"] = page_cursor

    response = requests.get(url, headers=headers, params=params)

    if response.status_code == 200:
        data_json = response.json()
        all_group_data.extend(data_json.get("data", []))

        page_cursor = data_json.get("next_page")
        if not page_cursor:
            break  
    else:
        print(f"Error: {response.status_code}")
        break  

if all_group_data:
    print("Data retrieved successfully!")
else:
    print("Issue: No data available to retrieve.")

# Initialize a list to hold parsed records
records = []

# Iterate through the data to extract bucketed data
for bucket in all_group_data:
    start_time = bucket.get("start_time")
    end_time = bucket.get("end_time")
    for result in bucket.get("results", []):
        records.append({
            "start_time": start_time,
            "end_time": end_time,
            "input_tokens": result.get("input_tokens", 0),
            "output_tokens": result.get("output_tokens", 0),
            "input_cached_tokens": result.get("input_cached_tokens", 0),
            "input_audio_tokens": result.get("input_audio_tokens", 0),
            "output_audio_tokens": result.get("output_audio_tokens", 0),
            "num_model_requests": result.get("num_model_requests", 0),
            "project_id": result.get("project_id", "N/A"),
            "user_id": result.get("user_id", "N/A"),
            "api_key_id": result.get("api_key_id", "N/A"),
            "model": result.get("model", "N/A"),
            "batch": result.get("batch", "N/A"),
            "service_tier": result.get("service_tier", "N/A")
        })

# Create a DataFrame from the records
df = pd.DataFrame(records)

# Convert Unix timestamps to datetime for readability
df['start_datetime'] = pd.to_datetime(df['start_time'], unit='s', errors='coerce')
df['end_datetime'] = pd.to_datetime(df['end_time'], unit='s', errors='coerce')

# Reorder columns for better readability
df = df[
    [
        "start_datetime", "end_datetime", "start_time", "end_time",
        "input_tokens", "output_tokens", "input_cached_tokens",
        "input_audio_tokens", "output_audio_tokens", "num_model_requests",
        "project_id", "user_id", "api_key_id", "model", "batch", "service_tier"
    ]
]

# Display the DataFrame
df.head()

# Group data by model and project_id and aggregate model request counts
grouped_by_model_project = (
    df.groupby(["model", "project_id"])
    .agg({
        "num_model_requests": "sum",
    })
    .reset_index()
)

# Determine unique models and project IDs for plotting and color mapping
models = sorted(grouped_by_model_project['model'].unique())
project_ids = sorted(grouped_by_model_project['project_id'].unique())
distinct_colors = [
    "#1f77b4", "#ff7f0e", "#2ca02c", "#d62728", "#9467bd",
    "#8c564b", "#e377c2", "#7f7f7f", "#bcbd22", "#17becf"
]
project_color_mapping = {pid: distinct_colors[i % len(distinct_colors)] for i, pid in enumerate(project_ids)}

# Calculate total number of requests per project_id for legend
project_totals = (
    grouped_by_model_project.groupby("project_id")["num_model_requests"].sum()
    .sort_values(ascending=False)  # Sort by highest total first
)

# Set up bar positions
n_models = len(models)
bar_width = 0.6
x = np.arange(n_models)

plt.figure(figsize=(12, 6))

# Plot stacked bars for each model
for model_idx, model in enumerate(models):
    # Filter data for the current model
    model_data = grouped_by_model_project[grouped_by_model_project['model'] == model]
    
    bottom = 0
    # Stack segments for each project ID within the bars
    for _, row in model_data.iterrows():
        color = project_color_mapping[row['project_id']]
        plt.bar(x[model_idx], row['num_model_requests'], width=bar_width,
                bottom=bottom, color=color)
        bottom += row['num_model_requests']

# Labeling and styling
plt.xlabel('Model')
plt.ylabel('Number of Model Requests')
plt.title('Total Model Requests by Model and Project ID Last 30 Days')
plt.xticks(x, models, rotation=45, ha="right")

# Create a sorted legend with totals
handles = [
    mpatches.Patch(
        color=project_color_mapping[pid],
        label=f"{pid} (Total: {total})"
    )
    for pid, total in project_totals.items()
]
plt.legend(handles=handles, bbox_to_anchor=(1.05, 1), loc='upper left')

plt.tight_layout()
plt.show()

records = []
for bucket in all_group_data:
    for result in bucket.get("results", []):
        records.append({
            "project_id": result.get("project_id", "N/A"),
            "num_model_requests": result.get("num_model_requests", 0),
        })

# Create a DataFrame
df = pd.DataFrame(records)

# Aggregate data by project_id
grouped_by_project = (
    df.groupby("project_id")
    .agg({"num_model_requests": "sum"})
    .reset_index()
)

# Visualize Pie Chart
if not grouped_by_project.empty:
    # Filter out rows where num_model_requests == 0
    filtered_grouped_by_project = grouped_by_project[grouped_by_project['num_model_requests'] > 0]
    
    # Calculate the total model requests after filtering
    total_requests = filtered_grouped_by_project['num_model_requests'].sum()
    
    if total_requests > 0:
        # Calculate percentage of total for each project
        filtered_grouped_by_project['percentage'] = (
            filtered_grouped_by_project['num_model_requests'] / total_requests
        ) * 100
        
        # Separate "Other" projects (below 5%)
        other_projects = filtered_grouped_by_project[filtered_grouped_by_project['percentage'] < 5]
        main_projects = filtered_grouped_by_project[filtered_grouped_by_project['percentage'] >= 5]
        
        # Sum up "Other" projects
        if not other_projects.empty:
            other_row = pd.DataFrame({
                "project_id": ["Other"],
                "num_model_requests": [other_projects['num_model_requests'].sum()],
                "percentage": [other_projects['percentage'].sum()]
            })
            filtered_grouped_by_project = pd.concat([main_projects, other_row], ignore_index=True)
        
        # Sort by number of requests for better legend organization
        filtered_grouped_by_project = filtered_grouped_by_project.sort_values(by="num_model_requests", ascending=False)
        
        # Main pie chart for distribution of model requests by project_id
        plt.figure(figsize=(10, 8))
        plt.pie(
            filtered_grouped_by_project['num_model_requests'], 
            labels=filtered_grouped_by_project['project_id'], 
            autopct=lambda p: f'{p:.1f}%\n({int(p * total_requests / 100):,})',
            startangle=140,
            textprops={'fontsize': 10}
        )
        plt.title('Distribution of Model Requests by Project ID', fontsize=14)
        plt.axis('equal')  # Equal aspect ratio ensures pie chart is circular.
        plt.tight_layout()
        plt.show()
        
        # If there are "Other" projects, generate a second pie chart for breakdown
        if not other_projects.empty:
            other_total_requests = other_projects['num_model_requests'].sum()
            
            plt.figure(figsize=(10, 8))
            plt.pie(
                other_projects['num_model_requests'], 
                labels=other_projects['project_id'], 
                autopct=lambda p: f'{p:.1f}%\n({int(p * other_total_requests / 100):,})',
                startangle=140,
                textprops={'fontsize': 10}
            )
            plt.title('Breakdown of "Other" Projects by Model Requests', fontsize=14)
            plt.axis('equal')  # Equal aspect ratio ensures pie chart is circular.
            plt.tight_layout()
            plt.show()
    else:
        print("Total model requests is zero. Pie chart will not be rendered.")
else:
    print("No grouped data available for pie chart.")

# Calculate start time: n days ago from now
days_ago = 30
start_time = int(time.time()) - (days_ago * 24 * 60 * 60)

# Define the Costs API endpoint
costs_url = "https://api.openai.com/v1/organization/costs"

# Initialize an empty list to store all data
all_costs_data = []

# Initialize pagination cursor
page_cursor = None

# Loop to handle pagination
while True:
    costs_params = {
        "start_time": start_time,  # Required: Start time (Unix seconds)
        "bucket_width": "1d",  # Optional: Currently only '1d' is supported
        "limit": 30,  # Optional: Number of buckets to return
    }

    if page_cursor:
        costs_params["page"] = page_cursor

    costs_response = requests.get(costs_url, headers=headers, params=costs_params)

    if costs_response.status_code == 200:
        costs_json = costs_response.json()
        all_costs_data.extend(costs_json.get("data", []))

        page_cursor = costs_json.get("next_page")
        if not page_cursor:
            break
    else:
        print(f"Error: {costs_response.status_code}")
        break

if all_costs_data:
    print("Costs data retrieved successfully!")
else:
    print("No costs data found.")

# Initialize a list to hold parsed cost records
cost_records = []

# Extract bucketed cost data from all_costs_data
for bucket in all_costs_data:
    start_time = bucket.get("start_time")
    end_time = bucket.get("end_time")
    for result in bucket.get("results", []):
        cost_records.append({
            "start_time": start_time,
            "end_time": end_time,
            "amount_value": result.get("amount", {}).get("value", 0),
            "currency": result.get("amount", {}).get("currency", "usd"),
            "line_item": result.get("line_item"),
            "project_id": result.get("project_id")
        })

# Create a DataFrame from the cost records
cost_df = pd.DataFrame(cost_records)

# Convert Unix timestamps to datetime for readability
cost_df['start_datetime'] = pd.to_datetime(cost_df['start_time'], unit='s')
cost_df['end_datetime'] = pd.to_datetime(cost_df['end_time'], unit='s')

# Display the first few rows of the DataFrame
cost_df.head()

if not cost_df.empty:
    # Ensure datetime conversion for 'start_datetime' column
    if 'start_datetime' not in cost_df.columns or not pd.api.types.is_datetime64_any_dtype(cost_df['start_datetime']):
        cost_df['start_datetime'] = pd.to_datetime(cost_df['start_time'], unit='s', errors='coerce')

    # Create a new column for just the date part of 'start_datetime'
    cost_df['date'] = cost_df['start_datetime'].dt.date
    
    # Group by date and sum the amounts
    cost_per_day = cost_df.groupby('date')['amount_value'].sum().reset_index()
    
    # Plot the data
    plt.figure(figsize=(12, 6))
    plt.bar(cost_per_day['date'], cost_per_day['amount_value'], width=0.6, color='skyblue', alpha=0.8)
    plt.xlabel('Date')
    plt.ylabel('Total Cost (USD)')
    plt.title('Total Cost per Day (Last 30 Days)')
    plt.xticks(rotation=45, ha='right')
    plt.tight_layout()
    plt.show()
else:
    print("No cost data available to plot.")