# How Upgrade Hints and Tier Information Are Exposed in Instagit's API Responses

> Discover how Instagit exposes upgrade hints and tier information in API responses via AnalysisResult, SSE stream events, and MCP CLI footer.

- Repository: [Instalabs AI/instagit](https://github.com/instalabsai/instagit)
- Tags: api-reference
- Published: 2026-02-16

---

**Instagit exposes upgrade hints and tier information through the `AnalysisResult` interface, populated from SSE stream events and rendered in the MCP server's CLI footer.**

The `instalabsAI/instagit` repository implements a Model Context Protocol (MCP) server that streams repository analysis from a remote API. Understanding how upgrade hints and tier information are exposed in Instagit's API responses is essential for developers integrating usage limits and billing notifications into their own MCP tools.

## Type Definitions for Tier and Usage Metadata

The foundation of this exposure lies in [`src/types.ts`](https://github.com/instalabsAI/instagit/blob/main/src/types.ts), where the **`AnalysisResult`** interface defines the contract between the API client and the MCP server. This interface includes three critical fields for usage tracking:

- **`tier`**: A string indicating the user's subscription level (e.g., "free", "pro")
- **`tokensRemaining`**: Numeric count of available credits left in the current billing period
- **`upgradeHint`**: An optional string containing contextual upgrade suggestions when limits are approached

## Extracting Usage Data from SSE Streams

The [`src/api.ts`](https://github.com/instalabsAI/instagit/blob/main/src/api.ts) file handles the actual communication with the Instagit API endpoint `/v1/responses`. Rather than using standard JSON request-response patterns, this implementation utilizes **Server-Sent Events (SSE)** to stream analysis results.

When the client receives an event of type **`response.completed`**, it extracts a `usage` object from the payload. The mapping logic translates the API's snake_case fields to the client's camelCase properties:

- `usage.tier` → `result.tier`
- `usage.tokens_remaining` → `result.tokensRemaining`
- `usage.upgrade_hint` → `result.upgradeHint`

This transformation occurs within the **`analyzeRepoStreaming`** function, which returns a fully populated `AnalysisResult` object to the caller.

## Rendering Tier Information in the MCP Server

Once the client library returns the `AnalysisResult`, the MCP server in [`src/index.ts`](https://github.com/instalabsAI/instagit/blob/main/src/index.ts) formats this data for display in the command-line interface. The server constructs a footer section that appears after the main analysis text.

The formatting logic conditionally appends usage information:

1. **Token counts** are displayed first (input, output, and total tokens)
2. **Tier information** follows, showing the current subscription level
3. **Remaining credits** appear when `tokensRemaining` is greater than zero
4. **Upgrade hints** are appended as a separate paragraph when present, providing context such as "Upgrade to Pro for unlimited repository size"

## Complete Data Flow from API to User

Understanding the full path of upgrade hints and tier information helps developers debug usage-related issues:

1. **Remote API** (`https://instagit--instagit-api-api.modal.run/v1/responses`) sends SSE events containing the `usage` object upon completion
2. **API Client** ([`src/api.ts`](https://github.com/instalabsAI/instagit/blob/main/src/api.ts)) parses the `response.completed` event and maps usage fields to the `AnalysisResult` interface
3. **MCP Server** ([`src/index.ts`](https://github.com/instalabsAI/instagit/blob/main/src/index.ts)) receives the result and formats a user-visible footer with tier, credits remaining, and upgrade suggestions
4. **End User** sees the formatted output in their CLI or IDE integration, including contextual hints about subscription limits

## Practical Implementation Examples

### Consuming Tier Data in Your Integration

```typescript
import { analyzeRepoStreaming } from "./api";

async function checkUsage() {
  const result = await analyzeRepoStreaming({
    repo: "github.com/owner/repo",
    prompt: "Analyze codebase architecture",
  });

  console.log(`Current tier: ${result.tier}`);
  console.log(`Credits remaining: ${result.tokensRemaining}`);
  
  if (result.upgradeHint) {
    console.warn(`Limit warning: ${result.upgradeHint}`);
  }
}

```

### Formatting Usage Data for Display

```typescript
// Simplified excerpt from src/index.ts
function formatResponse(result: AnalysisResult): string {
  let output = result.text;
  const footerParts: string[] = [];

  if (result.tier) {
    footerParts.push(`Tier: ${result.tier}`);
  }
  
  if (result.tokensRemaining > 0) {
    footerParts.push(`Credits: ${result.tokensRemaining}`);
  }

  if (footerParts.length) {
    output += "\n\n---\n" + footerParts.join(" | ");
  }

  if (result.upgradeHint) {
    output += `\n\n${result.upgradeHint}`;
  }

  return output;
}

```

## Summary

- **Type definitions** in [`src/types.ts`](https://github.com/instalabsAI/instagit/blob/main/src/types.ts) establish the `AnalysisResult` interface with `tier`, `tokensRemaining`, and `upgradeHint` fields
- **API client** in [`src/api.ts`](https://github.com/instalabsAI/instagit/blob/main/src/api.ts) extracts usage metadata from SSE `response.completed` events and maps snake_case API fields to camelCase result properties
- **MCP server** in [`src/index.ts`](https://github.com/instalabsAI/instagit/blob/main/src/index.ts) formats tier information and upgrade hints into a user-visible footer appended to analysis results
- **Data flow** follows a clear path: Remote API → SSE stream → Client mapping → Server formatting → CLI display

## Frequently Asked Questions

### What fields contain tier and upgrade information in the API response?

The Instagit API returns tier and upgrade metadata within the `usage` object of a `response.completed` SSE event. This object contains `tier` (string), `tokens_remaining` (number), and `upgrade_hint` (optional string), which the client library maps to `tier`, `tokensRemaining`, and `upgradeHint` in the `AnalysisResult` interface.

### How does the MCP server display upgrade hints to users?

The MCP server in [`src/index.ts`](https://github.com/instalabsAI/instagit/blob/main/src/index.ts) appends upgrade hints to the analysis output after a separator line. When `result.upgradeHint` is present, the server adds two newlines followed by the hint text directly to the response string, making it appear as a distinct message below the usage footer in the CLI interface.

### Can I access tier information programmatically without parsing the CLI output?

Yes, the `analyzeRepoStreaming` function in [`src/api.ts`](https://github.com/instalabsAI/instagit/blob/main/src/api.ts) returns a complete `AnalysisResult` object that includes the `tier`, `tokensRemaining`, and `upgradeHint` fields as typed properties. You can import this function directly and access these values programmatically without relying on the MCP server's string formatting.

### What happens when the API does not include an upgrade hint?

When the API response omits the `upgrade_hint` field, the `upgradeHint` property in the `AnalysisResult` object will be `undefined`. The MCP server checks for the presence of this field before appending it to the output, so no upgrade message appears in the CLI when the hint is not provided by the API.