Agents API Reference
Complete API documentation for HG Agents.
Base URL
https://phoenix.hginsights.com/api/agents/v1
Authentication
All endpoints require authentication via the Authorization header. HG Insights supports two methods:
API Key (Recommended)
Authorization: Bearer phx_your_api_key_here
To get your API key:
- Log into HG Insights at https://phoenix.hginsights.com
- Navigate to MCP in the sidebar
- Copy your API key from the MCP page
OAuth 2.1 Bearer Token
OAuth access tokens obtained through the OAuth 2.1 flow are also accepted:
Authorization: Bearer eyJhbGciOi...
See the Authentication guide for details on both methods.
Unauthorized Response (401)
{
"detail": "Missing Authorization header"
}
Endpoints
List Available Agents
Retrieve all agents available for your organization.
GET /v1/agents
Authorization: Bearer YOUR_API_KEY
Response:
[
{
"id": "account-research",
"name": "Account Research Brief",
"description": "Generate comprehensive account research briefs for target companies",
"current_version": 1
}
]
Get Agent Details
Retrieve configuration and capabilities for a specific agent.
GET /v1/agents/{agent_id}
Authorization: Bearer YOUR_API_KEY
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
agent_id | string | Agent identifier (e.g., account-research) |
Response:
{
"id": "account-research",
"name": "Account Research Brief",
"description": "Generate comprehensive account research briefs for sales enablement",
"params_override": {},
"tool_selection": {
"company_firmographic": true,
"company_technographic": true,
"company_spend": true,
"company_cloud_spend": true,
"company_fai": true,
"company_contracts": true,
"contact_search": true,
"contact_enrich": true,
"sec_filing_section": true,
"sec_full_text_search": true,
"web_search": true
},
"model_override": null,
"current_version": 1
}
Start Agent Run
Initiate a new agent run. Returns immediately with a run ID for polling.
POST /v1/agents/{agent_id}/runs
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
agent_id | string | Agent identifier |
Request Body:
{
"input": {
"domain": "salesforce.com"
},
"params": {
"depth": "standard",
"output_formats": ["html"]
},
"tool_selection": {
"company_firmographic": true,
"company_technographic": true,
"company_spend": true,
"company_cloud_spend": true,
"company_fai": true,
"company_contracts": false,
"contact_search": true,
"contact_enrich": true,
"sec_filing_section": true,
"sec_full_text_search": false,
"web_search": true
}
}
Request Fields:
| Field | Type | Required | Description |
|---|---|---|---|
input | object | Yes | Input data for the agent |
input.domain | string | One of domain/hgid | Company website domain |
input.hgid | string | One of domain/hgid | HG Insights company ID |
params | object | No | Execution parameters |
params.depth | string | No | Research depth: quick, standard, deep |
params.output_formats | array | No | Output formats: html, markdown, pdf |
tool_selection | object | No | Enable/disable specific tools |
Response:
{
"run_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "queued"
}
Error Response (400):
{
"detail": "Either 'domain' or 'hgid' must be provided"
}
Published version. REST and MCP runs use the published version of the agent selected when you call, not the saved draft. To change what an agent does, edit it and publish again. A call that waits in the run queue keeps the version it was queued with. If the agent's registration changes while a run starts, the call returns HTTP 409 "Registration changed during start; run again"; send it again.
Get Run Status
Check the status and progress of an agent run.
GET /v1/runs/{run_id}
Authorization: Bearer YOUR_API_KEY
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
run_id | string | Run identifier from start response |
Response (Queued):
{
"run_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "queued",
"created_at": "2024-01-26T09:59:00Z"
}
Response (Running):
{
"run_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "running",
"progress": 0.45,
"agent_version": 1,
"started_at": "2024-01-26T10:00:00Z",
"created_at": "2024-01-26T09:59:00Z"
}
Response (Succeeded):
{
"run_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "succeeded",
"progress": 1.0,
"agent_version": 1,
"cost_summary": {
"tool_credits": 5.0,
"llm_credits": 2.5,
"total_credits": 7.5
},
"started_at": "2024-01-26T10:00:00Z",
"finished_at": "2024-01-26T10:03:45Z",
"created_at": "2024-01-26T09:59:00Z",
"artifact_url": "/v1/runs/550e8400-e29b-41d4-a716-446655440000/artifacts"
}
Response (Failed):
{
"run_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "failed",
"progress": 0.3,
"agent_version": 1,
"error": "Tool execution failed: company_firmographic returned error",
"failed_tools": ["company_firmographic"],
"started_at": "2024-01-26T10:00:00Z",
"finished_at": "2024-01-26T10:01:15Z",
"created_at": "2024-01-26T09:59:00Z"
}
Status Values:
| Status | Description |
|---|---|
queued | Run accepted, waiting to start |
running | Agent is actively executing |
succeeded | Completed successfully |
partially_failed | Completed with some tool failures |
failed | Execution failed |
Get Run Artifacts
Retrieve generated artifacts (briefs, reports) from a completed run.
GET /v1/runs/{run_id}/artifacts
Authorization: Bearer YOUR_API_KEY
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
run_id | string | Run identifier |
Response:
{
"run_id": "550e8400-e29b-41d4-a716-446655440000",
"artifacts": [
{
"id": "brief",
"artifact_type": "html",
"url": "/v1/runs/550e8400-e29b-41d4-a716-446655440000/artifacts/brief.html",
"created_at": "2024-01-26T10:03:45Z",
"expires_at": null
}
]
}
Artifact Fields:
| Field | Type | Description |
|---|---|---|
id | string | Artifact identifier |
artifact_type | string | Type: html, markdown, pdf, json |
url | string | URL to download the artifact |
created_at | string | ISO 8601 timestamp |
expires_at | string | Expiration time (for pre-signed URLs) |
Get Run Trace
Retrieve detailed execution trace for debugging and auditing.
GET /v1/runs/{run_id}/trace
Authorization: Bearer YOUR_API_KEY
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
run_id | string | Run identifier |
Response:
{
"run_id": "550e8400-e29b-41d4-a716-446655440000",
"steps": [
{
"step_number": 1,
"step_type": "tool_call",
"description": "company_firmographic",
"started_at": "2024-01-26T10:00:05Z",
"finished_at": "2024-01-26T10:00:06Z",
"tool_calls": [],
"output": null,
"error": null
}
],
"model_usage": {
"provider": "openrouter",
"model": "anthropic/claude-3.5-sonnet",
"prompt_tokens": 10500,
"completion_tokens": 4500,
"total_tokens": 15000,
"cost_usd": 0.045
},
"errors": [],
"total_duration_ms": 185000,
"created_at": "2024-01-26T10:00:00Z"
}
Debug Endpoint (Development Only)
Get detailed debug information including raw tool inputs/outputs.
GET /v1/runs/{run_id}/debug
Authorization: Bearer YOUR_API_KEY
This endpoint returns internal execution details. Use for debugging only.
Response:
{
"run_id": "550e8400-e29b-41d4-a716-446655440000",
"organization_slug": "your-org",
"agent_id": "account-research",
"status": "succeeded",
"created_at": "2024-01-26T09:59:00Z",
"started_at": "2024-01-26T10:00:00Z",
"finished_at": "2024-01-26T10:03:45Z",
"artifact_url": "/v1/runs/550e8400-e29b-41d4-a716-446655440000/artifacts/brief.html"
}
Get Branding
Retrieve branding configuration for your organization.
GET /v1/settings/branding
Authorization: Bearer YOUR_API_KEY
Response:
{
"organization_slug": "your-org",
"branding": {
"logo_url": null,
"primary_color": null,
"secondary_color": null
},
"updated_at": "2024-01-26T10:00:00Z"
}
Update Branding
Update branding configuration for your organization.
PUT /v1/settings/branding
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Request Body:
{
"logo_url": "https://example.com/logo.png",
"primary_color": "#E2231A",
"secondary_color": "#1A73E8"
}
Response:
{
"organization_slug": "your-org",
"branding": {
"logo_url": "https://example.com/logo.png",
"primary_color": "#E2231A",
"secondary_color": "#1A73E8"
},
"updated_at": "2024-01-26T10:05:00Z"
}
Error Responses
All endpoints may return the following error formats:
Unauthorized (401)
{
"detail": "Invalid API key"
}
Not Found (404)
{
"detail": "Run 550e8400-e29b-41d4-a716-446655440000 not found"
}
Validation Error (400)
{
"detail": "Either 'domain' or 'hgid' must be provided"
}
Internal Error (500)
{
"detail": "An unexpected error occurred"
}
Rate Limits
| Resource | Limit | Window |
|---|---|---|
| Tool calls | 1,000 | per minute |
| Concurrent runs | 10 | per organization |
| Artifact downloads | 50 | per minute |
Rate limit headers are included in all responses:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1706264400
Webhooks (Coming Soon)
Configure webhooks to receive notifications when runs complete instead of polling.
{
"webhook_url": "https://your-app.com/webhooks/hg-insights",
"events": ["run.succeeded", "run.failed"],
"secret": "whsec_..."
}
Contact your account manager to enable webhooks.