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"
}

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

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

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.

Base URL​

Authentication​

API Key (Recommended)​

OAuth 2.1 Bearer Token​

Unauthorized Response (401)​

Endpoints​

List Available Agents​

Get Agent Details​

Start Agent Run​

Get Run Status​

Get Run Artifacts​

Get Run Trace​

Debug Endpoint (Development Only)​

Get Branding​

Update Branding​

Error Responses​

Unauthorized (401)​

Not Found (404)​

Validation Error (400)​

Internal Error (500)​

Rate Limits​

Webhooks (Coming Soon)​

Base URL

Authentication

API Key (Recommended)

OAuth 2.1 Bearer Token

Unauthorized Response (401)

Endpoints

List Available Agents

Get Agent Details

Start Agent Run

Get Run Status

Get Run Artifacts

Get Run Trace

Debug Endpoint (Development Only)

Get Branding

Update Branding

Error Responses

Unauthorized (401)

Not Found (404)

Validation Error (400)

Internal Error (500)

Rate Limits

Webhooks (Coming Soon)