Aiso API beta

Aiso API

Programmatic access to your AI visibility data. Query tracked prompts, brand mentions, visibility, sentiment, position, and the sources cited by ChatGPT and Gemini. All endpoints return JSON and authenticate with a per-account API key.

This API is in beta. Endpoints and response shapes may evolve.

One key per account

Add x-aiso-project-id to scope a call.

Brand visibility

Mentions, sentiment, and position.

Source intelligence

Domains and URLs cited by AI.

Authentication

Include your API key in the x-api-key header on every request. You have one key per account. For project-specific calls, also send x-aiso-project-id with the project UUID. Generate a key in the Aiso app . Keys are stored as SHA-256 hashes, so the raw key is shown once on creation and cannot be retrieved again.

curl

curl -X GET "https://app.getaiso.com/api/v1/projects" \
  -H "x-api-key: aiso_abc123..."

curl -X GET "https://app.getaiso.com/api/v1/prompts" \
  -H "x-api-key: aiso_abc123..." \
  -H "x-aiso-project-id: YOUR_PROJECT_UUID"

Rate limits

Default limits are 10 requests per minute and 20 requests per day per API key. Admins can adjust these per user. Every response includes headers you can use to manage retries.

Header	Description
`X-RateLimit-Limit`	Max requests in the current window.
`X-RateLimit-Remaining`	Requests remaining before throttling.
`X-RateLimit-Reset`	Seconds until the window resets.

Base URL

https://app.getaiso.com/api/v1

Models and filtering

Aiso tracks two AI models. Use gpt for OpenAI ChatGPT with web search and gemini for Google Gemini with Google Search grounding. Report endpoints accept a flexible query body with dates, pagination, dimensions, filters, and sort order.

Parameter	Type	Description
`start_date`	string (YYYY-MM-DD)	Snapshots on or after this date.
`end_date`	string (YYYY-MM-DD)	Snapshots on or before this date.
`limit`	number (1–10,000)	Max rows. Default 1,000.
`offset`	number	Skip N rows. Default 0.
`dimensions`	string[]	Break down by `prompt_id`, `model_id`, `date`, `week`, or `month`.
`filters`	object[]	`{ field, operator: "in" \| "not_in", values: [] }`
`order_by`	object[]	`{ field, direction: "asc" \| "desc" }`

Report body

{
  "start_date": "2025-09-01",
  "end_date": "2025-10-01",
  "dimensions": ["date"],
  "filters": [
    { "field": "model_id", "operator": "in", "values": ["gpt"] }
  ],
  "order_by": [{ "field": "visibility", "direction": "desc" }],
  "limit": 100
}

GET/projects

Project

Returns project metadata. Without x-aiso-project-id, it lists all projects with summary fields. With the header, it returns one project including full domain_data.

Response (single project)

{
  "data": {
    "id": "uuid",
    "domain": "example.com",
    "company_name": "Example Inc",
    "niche": "CRM Software",
    "topics": ["pricing", "features", "alternatives"],
    "competitors": ["Competitor A", "Competitor B"],
    "geography": "US",
    "current_step": 2,
    "has_tracking": false,
    "created_at": "2025-09-22T...",
    "updated_at": "2025-10-01T...",
    "domain_data": {
      "domain": "example.com",
      "companyName": "Example Inc",
      "niche": "CRM Software",
      "topics": ["pricing", "features", "alternatives"],
      "competitors": ["Competitor A", "Competitor B"],
      "geography": "US",
      "language": "English",
      "entityType": "brand"
    }
  }
}

POST/projects

Create a project

Requires domain only. The server runs domain analysis once, saves domain_data, and returns it. Optional fields: country, language, entity_type, and prompts. The response uses the same shape as the single-project GET and may take up to about two minutes.

Request

{
  "domain": "example.com",
  "country": "US",
  "language": "English",
  "entity_type": "brand"
}

GET/prompts

Prompts

List the prompts tracked in the project. Optionally filter by topic with ?topic=pricing.

Response

{
  "data": [
    {
      "id": "prompt-uuid",
      "text": "What is the best CRM for small businesses?",
      "topic": "alternatives",
      "intent": "informational",
      "funnel_stage": "awareness",
      "branded": "non-branded",
      "source": "generated"
    }
  ],
  "total_count": 42
}

GET/brands

Brands

List the tracked brands, meaning your brand plus its competitors.

Response

{
  "data": [
    { "name": "Example Inc", "is_own": true, "is_competitor": false },
    { "name": "Competitor A", "is_own": false, "is_competitor": true }
  ],
  "total_count": 5
}

GET/snapshots

Snapshots

List analysis snapshots. Each snapshot is one visibility analysis run.

Response

{
  "data": [
    {
      "id": "snap-uuid",
      "status": "complete",
      "prompts_count": 42,
      "run_at": "2025-10-01T12:00:00Z",
      "completed_at": "2025-10-01T12:05:00Z"
    }
  ],
  "total_count": 8
}

POST/reports/brands

Brand mentions

Measure visibility for your brand and competitors across tracked prompts. Each result includes mention rate, sentiment, and average position.

Filters: model_id, prompt_id, topic_id, and brand_id. Dimensions: prompt_id, model_id, date, week, month.

Request

curl -X POST "https://app.getaiso.com/api/v1/reports/brands" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "start_date": "2025-09-01",
  "end_date": "2025-10-01",
  "dimensions": ["date"],
  "filters": [
    { "field": "model_id", "operator": "in", "values": ["gpt"] }
  ],
  "order_by": [{ "field": "visibility", "direction": "desc" }],
  "limit": 100
}'

Response

{
  "data": [
    {
      "brand": { "name": "Example Inc" },
      "mention_count": 28,
      "visibility": 0.67,
      "visibility_count": 28,
      "visibility_total": 42,
      "sentiment": 72,
      "sentiment_sum": 14,
      "sentiment_count": 28,
      "position": 2.3,
      "position_sum": 64.4,
      "position_count": 28,
      "date": "2025-09-15"
    }
  ],
  "total_count": 150
}

Field	Description
`visibility`	Mention rate from 0 to 1. How often the brand appears across tracked prompts.
`mention_count`	Prompt responses where the brand was mentioned.
`sentiment`	Normalized 0 to 100 score. 50 is neutral, above 50 is positive, below 50 is negative.
`position`	Average rank position when mentioned, where 1 is first. Null if not mentioned.

POST/reports/domains

Sources

Find the domains cited by AI models in their responses. Filter by model_id or domain, then order by used_count or citation_count.

Request

curl -X POST "https://app.getaiso.com/api/v1/reports/domains" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2025-09-01",
    "order_by": [{ "field": "used_count", "direction": "desc" }],
    "limit": 20
  }'

Response

{
  "data": [
    {
      "domain": "g2.com",
      "domain_type": "ugc",
      "used_count": 34,
      "citation_count": 52,
      "citation_rate": 1.53
    }
  ],
  "total_count": 87
}

Field	Description
`used_count`	Times URLs from this domain appeared in AI responses.
`citation_count`	Total inline citations from this domain.
`citation_rate`	Citations per retrieval (`citation_count / used_count`).
`domain_type`	`you`, `competitor`, `ugc`, `editorial`, `corporate`, `reference`, `institutional`, or `other`.

POST/reports/urls

Source URLs

Drill into individual cited pages. Filter with model_id, domain, or url.

Response

{
  "data": [
    {
      "url": "https://g2.com/products/example/reviews",
      "domain": "g2.com",
      "domain_type": "ugc",
      "title": "Example Reviews 2025 | G2",
      "used_count": 12,
      "citation_count": 18,
      "citation_rate": 1.5
    }
  ],
  "total_count": 245
}

Common recipes

Ready-made request bodies for the questions teams ask most.

Overall visibility for all brands

POST /reports/brands

{ }

Daily visibility trend for your brand

POST /reports/brands

{
  "dimensions": ["date"],
  "filters": [
    { "field": "brand_id", "operator": "in", "values": ["Your Brand"] }
  ]
}

Visibility by AI model (GPT vs Gemini)

POST /reports/brands

{
  "dimensions": ["model_id"]
}

Weekly visibility trend

POST /reports/brands

{
  "dimensions": ["week"],
  "start_date": "2025-08-01"
}

Top cited domains (GPT only)

POST /reports/domains

{
  "filters": [
    { "field": "model_id", "operator": "in", "values": ["gpt"] }
  ],
  "order_by": [{ "field": "used_count", "direction": "desc" }],
  "limit": 10
}

URL drilldown for a specific domain

POST /reports/urls

{
  "filters": [
    { "field": "domain", "operator": "in", "values": ["g2.com"] }
  ],
  "order_by": [{ "field": "citation_count", "direction": "desc" }]
}

MCP (Cursor & Claude)

Connect Cursor, Claude Desktop, or any MCP host directly to your Aiso account. The hosted MCP server wraps the v1 API as tools — same API key, no local install.

1. Create an API key

Go to API keys and create a key. Copy it when shown — it cannot be retrieved again.

2. Add to Cursor

Create .cursor/mcp.json in your project (or edit ~/.cursor/mcp.json globally), then restart Cursor or reload MCP from Settings.

mcp.json

{
  "mcpServers": {
    "aiso": {
      "url": "https://app.getaiso.com/api/v1/mcp",
      "headers": {
        "x-api-key": "aiso_your_key_here",
        "x-aiso-project-id": "your_project_uuid"
      }
    }
  }
}

For local dev, use http://localhost:3000/api/v1/mcp instead. Use list_projects to discover project IDs, then set x-aiso-project-id in the headers.

Legacy stdio clients

If your MCP host does not support remote URLs yet, proxy the hosted endpoint with mcp-remote:

mcp.json (stdio)

{
  "mcpServers": {
    "aiso": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://app.getaiso.com/api/v1/mcp",
        "--header",
        "x-api-key:aiso_your_key_here",
        "--header",
        "x-aiso-project-id:your_project_uuid"
      ]
    }
  }
}

Project header

GET /projects without a project header lists all your projects. With x-aiso-project-id, it returns one project. All other project-scoped routes require the header, or ?project_id= on GET.

Setup and prompt writes

POST /projects accepts a domain and runs analysis once, so there is no separate analyze endpoint. Setup and prompt management are open to all API key holders. Each project allows one setup write and one prompt write via the API or MCP: further setup updates return 409 once setup exists, and further prompt writes return 409 once prompts exist. The initial POST /projects may include prompts in the same request. Prompt suggestion and generation require stored setup (domain_data) and do not write to the database, so call add_prompts to save.

Visibility reports

Snapshots, brand, domain, and URL reports, and fanout metrics require a completed visibility analysis run for the project. Until then, those tools return 403 with guidance to reach out at getaiso.com for help.

Available MCP tools

Tool	Description
`get_access`	Account limits and optional project info
`list_projects`	All projects for your account
`get_project`	One project with full domain_data
`list_prompts`	Tracked prompts
`list_brands`	Brands and competitors
`list_snapshots`	Analysis runs
`brand_visibility_report`	Visibility report
`domain_report`	Domain citations
`url_report`	URL citations
`get_fanout_metrics`	Query fanout analytics
`get_fanouts_context`	Fanouts dashboard context
`create_project`	Create project (domain analysis included)
`update_project`	Update project setup
`add_prompts`	Add prompts (one write per project)
`update_prompts`	Update prompts (before first add_prompts only)
`manage_topic`	Create, update, or delete topics (before first add_prompts only)
`suggest_topics`	AI-suggest topics (requires setup, preview only)
`suggest_prompts`	AI-suggest prompts (requires setup, preview only)
`generate_topic_prompts`	Generate prompts for a topic (requires setup, preview only)

Troubleshooting

Status	Meaning
`400`	Missing `x-aiso-project-id` on a project-scoped route, or missing required body field
`401`	Missing or invalid API key
`403`	Visibility data not available yet (analysis not run)
`409`	Setup or prompt write already completed for this project
`429`	Rate limit exceeded

MCP endpoint: https://app.getaiso.com/api/v1/mcp · Admin usage: /admin/api

Need conversations data?

The Aiso API is for tracking your brand’s visibility and the sources used in AI results. For public access to Aiso’s conversations dataset, use our separate Apify API.

Open Conversations API

Errors

Error responses always return { "error": "message" }.

Status	Meaning
`401`	Missing or invalid API key.
`403`	Visibility data not available yet.
`409`	Setup or prompt write already completed, or project limit reached.
`404`	Project or resource not found.
`429`	Rate limit exceeded.
`500`	Internal server error.