--- updatedAt: 2026-10-21T02:38:48.000Z agentTools: projectIndex: https://developers.jasper.ai/llms.txt --- # Retrieve GEO run by ID Returns the whole run, or only the sections named in `sections`. # OpenAPI definition ```json { "openapi": "3.1.0", "paths": { "/v1/geo/analyses/{configId}/runs/{runId}": { "get": { "description": "Returns the whole run, or only the sections named in `sections`.", "operationId": "getRun", "parameters": [ { "name": "configId", "required": true, "in": "path", "schema": { "example": "agc_ABC123", "type": "string" } }, { "name": "runId", "required": true, "in": "path", "schema": { "example": "aga_ABC123", "type": "string" } }, { "name": "sections", "required": false, "in": "query", "description": "Comma-separated run sections. Omit to return the whole run.", "schema": { "example": "overview,metrics,recommendations", "type": "string" } }, { "name": "page", "required": false, "in": "query", "description": "Page of the requested paginated section. Valid only when the request resolves to exactly one paginated section.", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Page size for the paginated section.", "schema": { "minimum": 1, "default": 20, "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeoRunResponseDto" } } } }, "404": { "description": "Run not found." } }, "security": [ { "X-API-Key": [] }, { "oauth2": [ "user" ] } ], "summary": "Retrieve GEO run by ID", "tags": [ "GEO" ] } } }, "info": { "title": "Jasper API", "description": "Jasper API", "version": "1.0", "contact": {} }, "tags": [ { "name": "GEO", "description": "" } ], "servers": [ { "url": "https://api.jasper.ai" } ], "components": { "securitySchemes": { "X-API-Key": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Workspace authentication using API key tokens in the X-API-Key header." }, "oauth2": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://api.jasper.ai/oauth2/authorize", "tokenUrl": "https://api.jasper.ai/oauth2/token", "refreshUrl": "https://api.jasper.ai/oauth2/token", "scopes": { "user:read": "Read user information", "user": "Read and write user information" } } }, "description": "User-level authentication using OAuth bearer tokens in the Authorization header." } }, "schemas": { "GeoFindingLocationDto": { "type": "object", "properties": { "title": { "type": "string", "example": "Pricing" }, "url": { "type": "string", "example": "https://www.jasper.ai/pricing" } }, "required": [ "title", "url" ] }, "GeoFindingActionDto": { "type": "object", "properties": { "instructions": { "type": "string", "description": "What to change on the page to resolve the finding." } }, "required": [ "instructions" ] }, "GeoFindingDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable ID of this finding within the run." }, "type": { "type": "string", "enum": [ "violation", "recommendation" ] }, "category": { "type": "string", "enum": [ "low-information-density", "missing-source-citations", "missing-summary", "poor-content-structure", "missing-faq", "missing-eeat-signals", "non-query-headings", "stale-content", "ambiguous-reference", "inconsistent-entity-naming", "poor-scannability", "format-mismatch", "missing-decision-criteria", "inverted-structure-missing", "missing-content" ] }, "severity": { "type": "string", "enum": [ "critical", "warning", "info" ] }, "topicClusterId": { "type": "string", "description": "Set when the finding belongs to a configured topic cluster." }, "topicClusterName": { "type": "string", "description": "Set when the finding belongs to a name-only proposed topic cluster." }, "location": { "description": "The page the finding was raised against. For `missing-content` findings this is a page that does not exist yet: `url` is a proposed path rather than an absolute URL, and `title` is a suggested headline.", "allOf": [ { "$ref": "#/components/schemas/GeoFindingLocationDto" } ] }, "description": { "type": "string", "description": "What is wrong, in natural language." }, "originalText": { "type": "string", "description": "The offending excerpt, when the finding points at specific copy." }, "action": { "description": "The remediation to apply.", "allOf": [ { "$ref": "#/components/schemas/GeoFindingActionDto" } ] } }, "required": [ "id", "type", "category", "severity", "location", "description", "action" ] }, "GeoPaginationDto": { "type": "object", "properties": { "totalRecords": { "type": "number", "description": "Findings matching the filters, across every page.", "example": 24 }, "page": { "type": "number", "example": 1 }, "pageSize": { "type": "number", "example": 20 }, "next": { "type": "string", "nullable": true, "description": "Link to the next page, carrying the same filters. `null` on the last page.", "example": "https://api.jasper.ai/v1/geo/analyses/agc_ABC123/runs/aga_ABC123/recommendations?page=2&limit=20" }, "prev": { "type": "string", "nullable": true, "description": "Link to the previous page, carrying the same filters. `null` on the first page.", "example": null } }, "required": [ "totalRecords", "page", "pageSize", "next", "prev" ] }, "GeoRunOverviewDto": { "type": "object", "properties": { "summary": { "type": "string", "description": "Natural-language summary of the run." } }, "required": [ "summary" ] }, "GeoRunSentimentThemeDto": { "type": "object", "properties": { "theme": { "type": "string", "description": "The theme the quote illustrates." }, "quote": { "type": "string", "description": "The excerpt of the AI answer behind the theme." }, "provider": { "type": "string", "enum": [ "chatgpt", "gemini", "claude", "perplexity" ], "description": "AI provider that gave the answer." }, "queryId": { "type": "string", "description": "ID of the tracked query the answer responded to." }, "query": { "type": "string", "description": "Text of the tracked query the answer responded to." } }, "required": [ "theme", "quote", "provider", "queryId", "query" ] }, "GeoRunSentimentDistributionDto": { "type": "object", "properties": { "positive": { "type": "number" }, "neutral": { "type": "number" }, "negative": { "type": "number" } }, "required": [ "positive", "neutral", "negative" ] }, "GeoRunSentimentDto": { "type": "object", "properties": { "summary": { "type": "string", "description": "Natural-language summary of how AI answers portray the brand." }, "workingWell": { "description": "Themes working in the brand’s favour.", "type": "array", "items": { "$ref": "#/components/schemas/GeoRunSentimentThemeDto" } }, "workingAgainst": { "description": "Themes working against the brand.", "type": "array", "items": { "$ref": "#/components/schemas/GeoRunSentimentThemeDto" } }, "distribution": { "description": "Split of brand mentions by sentiment.", "allOf": [ { "$ref": "#/components/schemas/GeoRunSentimentDistributionDto" } ] } }, "required": [ "summary", "workingWell", "workingAgainst", "distribution" ] }, "GeoLabelledScoreDto": { "type": "object", "properties": { "label": { "type": "string", "description": "Display label for the score." }, "value": { "type": "number" } }, "required": [ "label", "value" ] }, "GeoProviderShareOfVoiceDto": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "chatgpt", "gemini", "claude", "perplexity" ] }, "value": { "type": "number", "description": "The brand’s share of voice in this provider’s answers." } }, "required": [ "provider", "value" ] }, "GeoRunMetricsDto": { "type": "object", "properties": { "overall": { "description": "Composite of brand presence, citation rate and sentiment across providers and topic clusters.", "allOf": [ { "$ref": "#/components/schemas/GeoLabelledScoreDto" } ] }, "brandPresenceRate": { "description": "Share of tracked queries whose answers name the brand.", "allOf": [ { "$ref": "#/components/schemas/GeoLabelledScoreDto" } ] }, "citationRate": { "description": "Share of answers that cite the brand’s own content.", "allOf": [ { "$ref": "#/components/schemas/GeoLabelledScoreDto" } ] }, "brandSentiment": { "description": "How positively answers portray the brand.", "allOf": [ { "$ref": "#/components/schemas/GeoLabelledScoreDto" } ] }, "shareOfVoice": { "description": "Share of voice of the brand and each competitor, labelled by name.", "type": "array", "items": { "$ref": "#/components/schemas/GeoLabelledScoreDto" } }, "shareOfVoiceByProvider": { "description": "The brand’s share of voice per AI provider.", "type": "array", "items": { "$ref": "#/components/schemas/GeoProviderShareOfVoiceDto" } } }, "required": [ "overall", "brandPresenceRate", "citationRate", "brandSentiment", "shareOfVoice", "shareOfVoiceByProvider" ] }, "GeoRunProviderCoverageDto": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "chatgpt", "gemini", "claude", "perplexity" ] }, "totalQueries": { "type": "number", "description": "Tracked queries this provider was scheduled to answer." }, "successfulQueries": { "type": "number", "description": "Queries this provider answered." }, "coverageRate": { "type": "number", "minimum": 0, "maximum": 1, "description": "`successfulQueries / totalQueries`. `0` means the provider was unavailable for the run.", "example": 0.95 } }, "required": [ "provider", "totalQueries", "successfulQueries", "coverageRate" ] }, "GeoFindingSeverityCountsDto": { "type": "object", "properties": { "critical": { "type": "number" }, "warning": { "type": "number" }, "info": { "type": "number" } }, "required": [ "critical", "warning", "info" ] }, "GeoRunRecommendationsDto": { "type": "object", "properties": { "items": { "description": "The requested page of findings.", "type": "array", "items": { "$ref": "#/components/schemas/GeoFindingDto" } }, "pagination": { "description": "Paging over the run’s findings. Follow `next` for the remaining pages; `totalRecords` counts every finding, not just this page.", "allOf": [ { "$ref": "#/components/schemas/GeoPaginationDto" } ] }, "bySeverity": { "description": "Finding totals per severity, across every page.", "allOf": [ { "$ref": "#/components/schemas/GeoFindingSeverityCountsDto" } ] }, "byCategory": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Finding totals per category, across every page. Categories with no findings are omitted.", "example": { "missing-faq": 4, "stale-content": 2 } } }, "required": [ "items", "pagination", "bySeverity", "byCategory" ] }, "GeoRunCitationUrlDto": { "type": "object", "properties": { "url": { "type": "string", "example": "https://www.jasper.ai/pricing" }, "occurrences": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Times cited, keyed by AI provider.", "example": { "chatgpt": 3, "perplexity": 5 } } }, "required": [ "url", "occurrences" ] }, "GeoRunCitationDto": { "type": "object", "properties": { "hostname": { "type": "string", "example": "www.jasper.ai" }, "type": { "type": "string", "enum": [ "brand", "competitor", "community", "authority", "reference", "publisher", "other" ], "description": "What kind of site the hostname is." }, "occurrences": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Times cited, keyed by AI provider.", "example": { "chatgpt": 3, "perplexity": 5 } }, "urls": { "description": "The individual cited URLs on this hostname.", "type": "array", "items": { "$ref": "#/components/schemas/GeoRunCitationUrlDto" } } }, "required": [ "hostname", "type", "occurrences", "urls" ] }, "GeoRunTopicClusterQueryDto": { "type": "object", "properties": { "id": { "type": "string" }, "query": { "type": "string" } }, "required": [ "id", "query" ] }, "GeoRunBrandMentionDto": { "type": "object", "properties": { "domain": { "type": "string", "example": "jasper.ai" }, "count": { "type": "number", "description": "Times answers in this cluster mentioned the domain." } }, "required": [ "domain", "count" ] }, "GeoRunTopicClusterDto": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "queries": { "description": "Tracked queries in the cluster.", "type": "array", "items": { "$ref": "#/components/schemas/GeoRunTopicClusterQueryDto" } }, "brandMentions": { "description": "Mentions per domain across the cluster’s answers.", "type": "array", "items": { "$ref": "#/components/schemas/GeoRunBrandMentionDto" } } }, "required": [ "id", "name", "queries", "brandMentions" ] }, "GeoRunDto": { "type": "object", "properties": { "overview": { "description": "Natural-language summary of the run.", "allOf": [ { "$ref": "#/components/schemas/GeoRunOverviewDto" } ] }, "sentiment": { "description": "Sentiment summary, themes and distribution.", "allOf": [ { "$ref": "#/components/schemas/GeoRunSentimentDto" } ] }, "completedAt": { "type": "string", "description": "ISO 8601 timestamp the run completed at." }, "metrics": { "description": "Labelled scores: overall, brand presence, citation rate, sentiment and share of voice.", "allOf": [ { "$ref": "#/components/schemas/GeoRunMetricsDto" } ] }, "providerCoverage": { "description": "Per provider: queries attempted, succeeded, and coverage rate.", "type": "array", "items": { "$ref": "#/components/schemas/GeoRunProviderCoverageDto" } }, "recommendations": { "description": "One page of the run’s findings, with totals per severity and category.\n\nPaginated: `page` and `limit` select the page when this is the only paginated section requested. Follow `pagination.next`, which requests this section alone, to fetch the rest. Use `GET /v1/geo/analyses/{configId}/runs/{runId}/recommendations` to filter findings.", "allOf": [ { "$ref": "#/components/schemas/GeoRunRecommendationsDto" } ] }, "citations": { "description": "Hostnames cited by AI providers, typed and counted per provider.", "type": "array", "items": { "$ref": "#/components/schemas/GeoRunCitationDto" } }, "topicClusters": { "description": "Topic clusters, their queries, and brand mentions per domain.", "type": "array", "items": { "$ref": "#/components/schemas/GeoRunTopicClusterDto" } } } }, "GeoRunResponseDto": { "type": "object", "properties": { "requestId": { "type": "string", "example": "8393f82b3f6a4f6e8a405777b9305254" }, "resource": { "type": "string", "example": "knowledge" }, "data": { "$ref": "#/components/schemas/GeoRunDto" } }, "required": [ "requestId", "resource", "data" ] } } }, "x-readme": { "metrics-enabled": false } } ```