List prompt results

curl --request GET \
  --url https://api.surfais.com/v1/orgs/{orgId}/prompts/{promptId}/results \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.surfais.com/v1/orgs/{orgId}/prompts/{promptId}/results"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.surfais.com/v1/orgs/{orgId}/prompts/{promptId}/results', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": [
    {
      "run_date": "2023-12-25",
      "platform": "perplexity",
      "country": "<string>",
      "finalized_at": "2023-11-07T05:31:56Z",
      "brands": [
        {
          "brand_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "mentioned": true,
          "position": 0,
          "sentiment": 0
        }
      ],
      "brands_total": 0,
      "brands_truncated": true,
      "citations": [
        {
          "url": "<string>",
          "domain": "<string>",
          "cited": true
        }
      ]
    }
  ],
  "pagination": {
    "next_cursor": "<string>",
    "has_more": true
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  },
  "request_id": "<string>"
}

Results

List prompt results

Per-run results for a prompt.

One row per finalised run unit (platform × country × date), newest date first, with every tracked brand’s mention and the run’s citations. Finalised only: after a run completes, entity adjudication can still demote a mention, so pre-finalised rows are never served. A first page whose limit takes more than one paging statement is checked against the brand’s change token before and after the walk and walked again if it moved; a token still moving after the retries is 409 scan_in_progress with Retry-After (5s) rather than a page assembled from two scan generations — expect it while a scan of the brand runs (Pagination, above).

GET

orgs

{orgId}

prompts

{promptId}

results

List prompt results

curl --request GET \
  --url https://api.surfais.com/v1/orgs/{orgId}/prompts/{promptId}/results \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.surfais.com/v1/orgs/{orgId}/prompts/{promptId}/results"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.surfais.com/v1/orgs/{orgId}/prompts/{promptId}/results', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": [
    {
      "run_date": "2023-12-25",
      "platform": "perplexity",
      "country": "<string>",
      "finalized_at": "2023-11-07T05:31:56Z",
      "brands": [
        {
          "brand_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "mentioned": true,
          "position": 0,
          "sentiment": 0
        }
      ],
      "brands_total": 0,
      "brands_truncated": true,
      "citations": [
        {
          "url": "<string>",
          "domain": "<string>",
          "cited": true
        }
      ]
    }
  ],
  "pagination": {
    "next_cursor": "<string>",
    "has_more": true
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  },
  "request_id": "<string>"
}

Authorizations

Authorization

string

header

required

A Surfais API key — an organisation key or a partner key. Issued by Surfais; shown once. Rotate by creating a new key, then revoking the old one.

Path Parameters

orgId

string<uuid>

required

Organisation id. Org keys: the key's own org. Partner keys: any org with an active link. Anything else is 404.

Pattern:

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

promptId

string<uuid>

required

Prompt id within the org; 404 when not in the org.

Pattern:

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Query Parameters

limit

integer

default:50

Page size (1–200). Default 50.

Required range: 1 <= x <= 200

cursor

string

Opaque cursor from a previous page's pagination.next_cursor. It pins the walk — its sort anchor, the resolved date window and the FILTERS the first page ran under — so continue with the cursor alone: omitted filters are restored from it. Naming a different value for one of them is 400 invalid_cursor (details.reason = "filter_changed", details.parameter the one that differs); start again from the first page to change a filter.

Maximum string length: 2048

from

string<date>

Window start (inclusive). Default: to minus 30 days.

Pattern: ^\d{4}-\d{2}-\d{2}$

string<date>

Window end (inclusive). Default: today (UTC). Max span 366 days; from after to is 400 validation_error. On a paginated endpoint the resolved window is pinned by the first page and carried in the cursor — continue with the cursor alone; naming a different from/to on a continuation is 400 invalid_cursor (details.reason = "window_changed").

Pattern: ^\d{4}-\d{2}-\d{2}$

platform

enum<string>

Scanned AI platform id.

Available options:

perplexity,

chatgpt,

gemini,

claude,

ai_overviews

country

string

Runs in this market. Trimmed and upper-cased to match storage; accepts any token PromptResult.country can return. A token nothing stores returns an empty page, not an error.

Required string length: 1 - 256

Pattern: ^[^\u0000-\u001f\u007f-\u009f]+$

Response

Finalised run results.

data

object[]

required

Show child attributes

pagination

object

required

Show child attributes

Get started

Core concepts

Webhooks

Guides

Reference

Resources

List prompt results

Authorizations

Path Parameters

Query Parameters

Response