Skip to main content

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:

Authorization: Bearer phx_your_api_key_here

To get your API key:

  1. Log into HG Insights at https://phoenix.hginsights.com
  2. Navigate to MCP in the sidebar
  3. 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:

ParameterTypeDescription
agent_idstringAgent 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:

ParameterTypeDescription
agent_idstringAgent 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:

FieldTypeRequiredDescription
inputobjectYesInput data for the agent
input.domainstringOne of domain/hgidCompany website domain
input.hgidstringOne of domain/hgidHG Insights company ID
paramsobjectNoExecution parameters
params.depthstringNoResearch depth: quick, standard, deep
params.output_formatsarrayNoOutput formats: html, markdown, pdf
tool_selectionobjectNoEnable/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:

ParameterTypeDescription
run_idstringRun 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:

StatusDescription
queuedRun accepted, waiting to start
runningAgent is actively executing
succeededCompleted successfully
partially_failedCompleted with some tool failures
failedExecution 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:

ParameterTypeDescription
run_idstringRun 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:

FieldTypeDescription
idstringArtifact identifier
artifact_typestringType: html, markdown, pdf, json
urlstringURL to download the artifact
created_atstringISO 8601 timestamp
expires_atstringExpiration 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:

ParameterTypeDescription
run_idstringRun 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
warning

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​

ResourceLimitWindow
Tool calls1,000per minute
Concurrent runs10per organization
Artifact downloads50per 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.