Skip to Content

Get a user

GEThttps://api.respan.ai/api/users/{customer_identifier}/

Returns the user’s editable profile and current budget usage.

Servers

https://api.respan.ai: Respan API Server

Authentication

RespanApiKey

Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.

HTTP scheme: bearer; format: Respan API key.

HTTP
Authorization: Bearer $RESPAN_API_KEY

Or:

DashboardJwt

Use a dashboard JWT only for dashboard-authenticated endpoints. Respan API-key endpoints use the respanApiKey auth field instead.

HTTP scheme: bearer; format: Dashboard JWT.

HTTP
Authorization: Bearer $RESPAN_DASHBOARD_JWT

Path parameters

Parameter Type Required Description and constraints
customer_identifier string Required
Your unique identifier for this user.

Query parameters

Parameter Type Required Description and constraints
environment string Optional
Optional environment filter. If omitted, the backend uses the environment implied by your auth context when applicable.
Allowed: "prod", "test"
Example: "prod"

Responses

200

User details.

application/json

Field Type Requirement Description and constraints
$ object Body
-
id string Optional
User identifier.
name string or null Optional
User display name.
email string or null Optional
User email address.
customer_identifier string Optional
Your unique identifier for the user.
environment string Optional
User environment.
Allowed: "prod", "test"
total_budget number or null Optional
Lifetime spending budget in USD.
period_budget number or null Optional
Current period budget in USD.
organization_name string or null Optional
Owning organization name.
total_period_usage number Optional
Usage in the current budget period in USD.
period_start string Optional
Start of the current budget period.
Format: date-time
period_end string or null Optional
End of the current budget period.
Format: date-time
budget_duration string Optional
Budget renewal period.
Allowed: "daily", "weekly", "monthly"
updated_at string Optional
Last update timestamp.
Format: date-time

OpenAPI response schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "User identifier."
    },
    "name": {
      "type": "string",
      "nullable": true,
      "description": "User display name."
    },
    "email": {
      "type": "string",
      "nullable": true,
      "description": "User email address."
    },
    "customer_identifier": {
      "type": "string",
      "description": "Your unique identifier for the user."
    },
    "environment": {
      "type": "string",
      "enum": [
        "prod",
        "test"
      ],
      "description": "User environment."
    },
    "total_budget": {
      "type": "number",
      "nullable": true,
      "description": "Lifetime spending budget in USD."
    },
    "period_budget": {
      "type": "number",
      "nullable": true,
      "description": "Current period budget in USD."
    },
    "organization_name": {
      "type": "string",
      "nullable": true,
      "description": "Owning organization name."
    },
    "total_period_usage": {
      "type": "number",
      "description": "Usage in the current budget period in USD."
    },
    "period_start": {
      "type": "string",
      "format": "date-time",
      "description": "Start of the current budget period."
    },
    "period_end": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "End of the current budget period."
    },
    "budget_duration": {
      "type": "string",
      "enum": [
        "daily",
        "weekly",
        "monthly"
      ],
      "description": "Budget renewal period."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "Last update timestamp."
    }
  }
}
Example
JSON
{ "id": "user_123", "name": "John Doe", "email": "john@example.com", "customer_identifier": "user_123", "environment": "prod", "total_budget": 1000, "period_budget": 100, "organization_name": "Acme Inc", "total_period_usage": 45.67, "period_start": "2025-12-01T00:00:00Z", "period_end": null, "budget_duration": "monthly", "updated_at": "2025-12-29T10:30:00Z" }

403

The API key is missing, invalid or expired.

application/json

Field Type Requirement Description and constraints
$ object Body
-
detail string Required in parent
-

OpenAPI response schema

{
  "type": "object",
  "required": [
    "detail"
  ],
  "properties": {
    "detail": {
      "type": "string"
    }
  }
}
Example
JSON
{ "detail": "Your API key is invalid or expired, please check your API key in the platform settings." }

404

Not Found

application/json

Field Type Requirement Description and constraints
$ object Body
-
detail string Optional
Example: "Customer user not found"

OpenAPI response schema

{
  "type": "object",
  "properties": {
    "detail": {
      "type": "string",
      "example": "Customer user not found"
    }
  }
}

429

Rate Limited

application/json

Field Type Requirement Description and constraints
$ object Body
-
detail string Optional
Example: "Request was throttled. Expected available in 1 second."

OpenAPI response schema

{
  "type": "object",
  "properties": {
    "detail": {
      "type": "string",
      "example": "Request was throttled. Expected available in 1 second."
    }
  }
}

500

Internal Server Error

application/json

Field Type Requirement Description and constraints
$ object Body
-
detail string Optional
Example: "Internal server error"

OpenAPI response schema

{
  "type": "object",
  "properties": {
    "detail": {
      "type": "string",
      "example": "Internal server error"
    }
  }
}

OpenAPI source

The operation and referenced components below retain the complete OpenAPI definitions, including constraints and examples.

OpenAPI operation

{
  "summary": "Get a user",
  "operationId": "retrieveUser",
  "tags": [
    "Users"
  ],
  "description": "Returns the user's editable profile and current budget usage.",
  "parameters": [
    {
      "name": "customer_identifier",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Your unique identifier for this user."
    },
    {
      "name": "environment",
      "in": "query",
      "schema": {
        "type": "string",
        "enum": [
          "prod",
          "test"
        ]
      },
      "description": "Optional environment filter. If omitted, the backend uses the environment implied by your auth context when applicable.",
      "example": "prod"
    }
  ],
  "responses": {
    "200": {
      "description": "User details.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "User identifier."
              },
              "name": {
                "type": "string",
                "nullable": true,
                "description": "User display name."
              },
              "email": {
                "type": "string",
                "nullable": true,
                "description": "User email address."
              },
              "customer_identifier": {
                "type": "string",
                "description": "Your unique identifier for the user."
              },
              "environment": {
                "type": "string",
                "enum": [
                  "prod",
                  "test"
                ],
                "description": "User environment."
              },
              "total_budget": {
                "type": "number",
                "nullable": true,
                "description": "Lifetime spending budget in USD."
              },
              "period_budget": {
                "type": "number",
                "nullable": true,
                "description": "Current period budget in USD."
              },
              "organization_name": {
                "type": "string",
                "nullable": true,
                "description": "Owning organization name."
              },
              "total_period_usage": {
                "type": "number",
                "description": "Usage in the current budget period in USD."
              },
              "period_start": {
                "type": "string",
                "format": "date-time",
                "description": "Start of the current budget period."
              },
              "period_end": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "End of the current budget period."
              },
              "budget_duration": {
                "type": "string",
                "enum": [
                  "daily",
                  "weekly",
                  "monthly"
                ],
                "description": "Budget renewal period."
              },
              "updated_at": {
                "type": "string",
                "format": "date-time",
                "description": "Last update timestamp."
              }
            }
          },
          "example": {
            "id": "user_123",
            "name": "John Doe",
            "email": "john@example.com",
            "customer_identifier": "user_123",
            "environment": "prod",
            "total_budget": 1000,
            "period_budget": 100,
            "organization_name": "Acme Inc",
            "total_period_usage": 45.67,
            "period_start": "2025-12-01T00:00:00Z",
            "period_end": null,
            "budget_duration": "monthly",
            "updated_at": "2025-12-29T10:30:00Z"
          }
        }
      }
    },
    "403": {
      "$ref": "#/components/responses/InvalidApiKey"
    },
    "404": {
      "description": "Not Found",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "detail": {
                "type": "string",
                "example": "Customer user not found"
              }
            }
          }
        }
      }
    },
    "429": {
      "description": "Rate Limited",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "detail": {
                "type": "string",
                "example": "Request was throttled. Expected available in 1 second."
              }
            }
          }
        }
      }
    },
    "500": {
      "description": "Internal Server Error",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "detail": {
                "type": "string",
                "example": "Internal server error"
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "RespanApiKey": []
    },
    {
      "DashboardJwt": []
    }
  ]
}

OpenAPI path metadata

{}

Referenced OpenAPI components

{
  "responses": {
    "InvalidApiKey": {
      "description": "The API key is missing, invalid or expired.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "detail"
            ],
            "properties": {
              "detail": {
                "type": "string"
              }
            }
          },
          "example": {
            "detail": "Your API key is invalid or expired, please check your API key in the platform settings."
          }
        }
      }
    }
  },
  "securitySchemes": {
    "DashboardJwt": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "Dashboard JWT",
      "description": "Use a dashboard JWT only for dashboard-authenticated endpoints. Respan API-key endpoints use the respanApiKey auth field instead.",
      "x-fern-bearer": {
        "name": "dashboardJwt",
        "env": "RESPAN_DASHBOARD_JWT"
      }
    },
    "RespanApiKey": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "Respan API key",
      "description": "Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.",
      "x-fern-bearer": {
        "name": "respanApiKey",
        "env": "RESPAN_API_KEY"
      }
    }
  }
}