> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heralded.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Week Timeline

> The week's observed changes, results linked to work, and competitor moves.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/brands/{brand_id}/week-timeline
openapi: 3.1.0
info:
  description: >-
    Access to one organization's brands, as the member who created the API key.
    A read-only key reads; a full-access key also starts, edits and runs that
    member's Snapshots on the organization's Snapshot credits. Each key may make
    120 requests a minute. Separate organization service tokens can start
    Snapshots and Full audits and read service audits. Every error is an RFC
    9457 problem (`application/problem+json`) whose `code` names it.
  summary: Read your brands' AI visibility and run Snapshots in Heralded.
  title: Heralded API
  version: '1'
servers:
  - url: https://api.heralded.ai
security: []
paths:
  /v1/brands/{brand_id}/week-timeline:
    get:
      tags:
        - v1
      summary: Get Week Timeline
      description: >-
        The week's observed changes, results linked to work, and competitor
        moves.
      operationId: listWeekTimeline
      parameters:
        - description: The brand's UUID from listBrands.
          in: path
          name: brand_id
          required: true
          schema:
            description: The brand's UUID from listBrands.
            format: uuid
            title: Brand Id
            type: string
        - description: Maximum rows (100).
          in: query
          name: limit
          required: false
          schema:
            default: 20
            description: Maximum rows (100).
            maximum: 100
            minimum: 1
            title: Limit
            type: integer
        - description: Prior next_cursor; keep filters and limit.
          in: query
          name: cursor
          required: false
          schema:
            anyOf:
              - maxLength: 4096
                type: string
              - type: 'null'
            description: Prior next_cursor; keep filters and limit.
            title: Cursor
        - description: Completed scan id cutoff.
          in: query
          name: as_of
          required: false
          schema:
            anyOf:
              - format: uuid
                type: string
              - type: 'null'
            description: Completed scan id cutoff.
            title: As Of
        - description: Rows to skip; prefer cursor paging.
          in: query
          name: offset
          required: false
          schema:
            default: 0
            description: Rows to skip; prefer cursor paging.
            minimum: 0
            title: Offset
            type: integer
        - description: Monday starting the week; omit for this week.
          in: query
          name: week
          required: false
          schema:
            anyOf:
              - format: date
                type: string
              - type: 'null'
            description: Monday starting the week; omit for this week.
            title: Week
        - description: UTC day within the selected week; pages rows in lead order.
          in: query
          name: day
          required: false
          schema:
            anyOf:
              - format: date
                type: string
              - type: 'null'
            description: UTC day within the selected week; pages rows in lead order.
            title: Day
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WeekTimeline'
          description: Successful Response
        '400':
          content:
            application/problem+json:
              example:
                code: invalid_cursor
                detail: The cursor is invalid or belongs to a different query.
                instance: example-request-id
                status: 400
                title: Bad Request
                type: https://docs.heralded.ai/errors-and-limits#invalid_cursor
              schema:
                $ref: '#/components/schemas/Problem'
          description: The cursor is invalid or belongs to a different query.
        '401':
          content:
            application/problem+json:
              example:
                code: invalid_token
                detail: >-
                  The Authorization header carries no API key Heralded knows: it
                  is missing, mistyped, revoked or expired.
                instance: example-request-id
                status: 401
                title: Unauthorized
                type: https://docs.heralded.ai/errors-and-limits#invalid_token
              schema:
                $ref: '#/components/schemas/Problem'
          description: No API key, or one that is unknown, revoked or expired.
          headers:
            WWW-Authenticate:
              schema:
                example: Bearer
                type: string
        '404':
          content:
            application/problem+json:
              example:
                code: not_found
                detail: Nothing here that this API key can read.
                instance: example-request-id
                status: 404
                title: Not Found
                type: https://docs.heralded.ai/errors-and-limits#not_found
              schema:
                $ref: '#/components/schemas/Problem'
          description: No such brand or answer, or the key's owner cannot read it.
        '409':
          content:
            application/problem+json:
              example:
                code: workspace_archived
                detail: The API key's organization is archived.
                instance: example-request-id
                status: 409
                title: Conflict
                type: https://docs.heralded.ai/errors-and-limits#workspace_archived
              schema:
                $ref: '#/components/schemas/Problem'
          description: The API key's organization is archived.
        '422':
          content:
            application/problem+json:
              example:
                code: invalid_request
                detail: The request's parameters are invalid; `errors` names each one.
                errors:
                  - loc:
                      - query
                      - limit
                    msg: Input should be less than or equal to 100
                    type: less_than_equal
                instance: example-request-id
                status: 422
                title: Unprocessable Content
                type: https://docs.heralded.ai/errors-and-limits#invalid_request
              schema:
                $ref: '#/components/schemas/ValidationProblem'
          description: A path or query parameter is invalid.
        '429':
          content:
            application/problem+json:
              example:
                code: rate_limited
                detail: >-
                  This caller is past its requests for the minute. Retry after
                  the seconds in Retry-After.
                instance: example-request-id
                rate_limit:
                  limit: 120
                  remaining: 0
                  reset: 60
                  window: 60
                status: 429
                title: Too Many Requests
                type: https://docs.heralded.ai/errors-and-limits#rate_limited
              schema:
                $ref: '#/components/schemas/RateLimitProblem'
          description: The API key made more than 120 requests in the minute.
          headers:
            Retry-After:
              description: Seconds until the key may call again.
              schema:
                example: 60
                type: integer
      security:
        - apiKey: []
components:
  schemas:
    WeekTimeline:
      examples:
        - days: []
          limit: 20
          meta:
            data_as_of: null
            last_attempt_failed: false
            partial: false
            query: {}
            surfaces: {}
            updating: false
          next_cursor: null
          offset: 0
          rows: []
          total: 0
          week: '2026-10-26'
      properties:
        days:
          description: The week's observed days, newest first.
          items:
            $ref: '#/components/schemas/TimelineDay'
          title: Days
          type: array
        limit:
          description: Maximum observations returned.
          title: Limit
          type: integer
        meta:
          $ref: '#/components/schemas/Meta'
          description: Normalized query and newest included scan.
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Pass as cursor with the same query to read the next page; null at
            the end.
          title: Next Cursor
        offset:
          description: Observations skipped.
          title: Offset
          type: integer
        rows:
          description: A page of observed events, newest first.
          items:
            $ref: '#/components/schemas/TimelineItem'
          title: Rows
          type: array
        total:
          description: Observations in the selected week.
          title: Total
          type: integer
        week:
          description: The Monday starting the week, in UTC.
          format: date
          title: Week
          type: string
      required:
        - meta
        - next_cursor
        - total
        - limit
        - offset
        - week
        - rows
        - days
      title: WeekTimeline
      type: object
    Problem:
      description: An RFC 9457 problem linking its code to human-readable documentation.
      properties:
        code:
          title: Code
          type: string
        detail:
          title: Detail
          type: string
        instance:
          default: ''
          title: Instance
          type: string
        status:
          title: Status
          type: integer
        title:
          title: Title
          type: string
        type:
          title: Type
          type: string
      required:
        - type
        - title
        - status
        - detail
        - code
        - instance
      title: Problem
      type: object
    ValidationProblem:
      properties:
        code:
          title: Code
          type: string
        detail:
          title: Detail
          type: string
        errors:
          items:
            $ref: '#/components/schemas/ValidationIssue'
          title: Errors
          type: array
        instance:
          default: ''
          title: Instance
          type: string
        status:
          title: Status
          type: integer
        title:
          title: Title
          type: string
        type:
          title: Type
          type: string
      required:
        - type
        - title
        - status
        - detail
        - code
        - instance
        - errors
      title: ValidationProblem
      type: object
    RateLimitProblem:
      properties:
        code:
          title: Code
          type: string
        detail:
          title: Detail
          type: string
        instance:
          default: ''
          title: Instance
          type: string
        rate_limit:
          $ref: '#/components/schemas/RateLimitValues'
        status:
          title: Status
          type: integer
        title:
          title: Title
          type: string
        type:
          title: Type
          type: string
      required:
        - type
        - title
        - status
        - detail
        - code
        - instance
        - rate_limit
      title: RateLimitProblem
      type: object
    TimelineDay:
      properties:
        date:
          description: The observation day in UTC.
          format: date
          title: Date
          type: string
        lead:
          $ref: '#/components/schemas/TimelineItem'
          description: The day's lead observation.
        others:
          description: Other observations on this day.
          title: Others
          type: integer
      required:
        - date
        - lead
        - others
      title: TimelineDay
      type: object
    Meta:
      properties:
        data_as_of:
          anyOf:
            - $ref: '#/components/schemas/DataAsOf'
            - type: 'null'
        last_attempt_failed:
          default: false
          description: The newest attempt failed; the last good result is displayed.
          title: Last Attempt Failed
          type: boolean
        partial:
          default: false
          description: The displayed response includes a partial report.
          title: Partial
          type: boolean
        query:
          additionalProperties:
            $ref: '#/components/schemas/JsonValue'
          title: Query
          type: object
        surfaces:
          additionalProperties:
            $ref: '#/components/schemas/SurfaceFreshness'
          description: >-
            Freshness by Command Center surface key. Each entry describes its
            own displayed result, including results without a scan.
          title: Surfaces
          type: object
        updating:
          default: false
          description: A newer result is being produced or is not yet displayed.
          title: Updating
          type: boolean
      required:
        - query
        - data_as_of
        - partial
        - updating
        - last_attempt_failed
        - surfaces
      title: Meta
      type: object
    TimelineItem:
      properties:
        action_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: The work behind a result; null for other observations.
          title: Action Id
        event:
          description: The source's observation kind or result signal.
          title: Event
          type: string
        id:
          description: Stable identity of this observation in the week.
          title: Id
          type: string
        kind:
          description: A change, a work result or a competitor move.
          enum:
            - change
            - result
            - competitor
          title: Kind
          type: string
        observed_at:
          description: When the event was observed.
          format: date-time
          title: Observed At
          type: string
        result:
          anyOf:
            - $ref: '#/components/schemas/ResultStep'
            - type: 'null'
          description: The kind-specific result step, retaining its measured state.
        target:
          anyOf:
            - $ref: '#/components/schemas/V1ChangeTarget'
            - type: 'null'
          description: The subject and filters supporting the observation.
        work_href:
          anyOf:
            - type: string
            - type: 'null'
          description: Link to that work; null for other observations.
          title: Work Href
      required:
        - id
        - kind
        - observed_at
        - event
        - target
        - action_id
        - work_href
        - result
      title: TimelineItem
      type: object
    ValidationIssue:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Loc
          type: array
        msg:
          title: Msg
          type: string
        type:
          title: Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationIssue
      type: object
    RateLimitValues:
      properties:
        limit:
          title: Limit
          type: integer
        remaining:
          title: Remaining
          type: integer
        reset:
          title: Reset
          type: integer
        window:
          title: Window
          type: integer
      required:
        - limit
        - window
        - remaining
        - reset
      title: RateLimitValues
      type: object
    DataAsOf:
      properties:
        completed_at:
          format: date-time
          title: Completed At
          type: string
        id:
          format: uuid
          title: Id
          type: string
      required:
        - id
        - completed_at
      title: DataAsOf
      type: object
    JsonValue: {}
    SurfaceFreshness:
      properties:
        as_of:
          anyOf:
            - $ref: '#/components/schemas/SurfaceAsOf'
            - type: 'null'
          description: The result displayed here.
        last_attempt_failed:
          default: false
          description: The newest attempt failed; any displayed result is retained.
          title: Last Attempt Failed
          type: boolean
        partial:
          default: false
          description: The displayed report is partial.
          title: Partial
          type: boolean
        updating:
          default: false
          description: A newer attempt exists whose result is not yet displayed.
          title: Updating
          type: boolean
      required:
        - as_of
        - partial
        - updating
        - last_attempt_failed
      title: SurfaceFreshness
      type: object
    ResultStep:
      properties:
        answer_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: Answer to open when this signal has recoverable answer evidence.
          title: Answer Id
        at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: Observation time, or measurement due date while pending.
          title: At
        citation:
          anyOf:
            - $ref: '#/components/schemas/FirstCitation'
            - type: 'null'
          description: Qualifying citation evidence; null for other signals.
        display_name:
          anyOf:
            - type: string
            - type: 'null'
          description: Engine display name when the signal concerns one engine.
          title: Display Name
        label:
          description: Result step or measured outcome in customer-facing words.
          title: Label
          type: string
        metric:
          anyOf:
            - enum:
                - mentioned
                - recommended
              type: string
            - type: 'null'
          description: Verified answer metric; null for observations and other outcomes.
          title: Metric
        prompt:
          anyOf:
            - type: string
            - type: 'null'
          description: Prompt text when the signal concerns an answer.
          title: Prompt
        reason:
          anyOf:
            - type: string
            - type: 'null'
          description: Reason a signal could not be checked; null otherwise.
          title: Reason
        signal:
          anyOf:
            - enum:
                - live
                - crawled
                - ranked
                - search_console
                - cited
                - moved
              type: string
            - const: measured
              type: string
          description: Signal this observation concerns.
          title: Signal
        state:
          anyOf:
            - enum:
                - good
                - no_change
                - couldnt_check
                - pending
              type: string
            - enum:
                - not_connected
                - no_effect
                - fell
                - inconclusive
              type: string
          description: >-
            Observed, pending, unchanged, unavailable, or measured outcome
            state.
          title: State
        summary:
          anyOf:
            - type: string
            - type: 'null'
          description: Observed result; null while pending.
          title: Summary
        tone:
          description: Success, neutral watching, or warning for a failed read.
          enum:
            - good
            - neutral
            - warning
          title: Tone
          type: string
      required:
        - signal
        - tone
        - summary
        - reason
        - at
        - answer_id
        - display_name
        - prompt
        - citation
        - label
        - state
        - metric
      title: ResultStep
      type: object
    V1ChangeTarget:
      properties:
        filters:
          $ref: '#/components/schemas/ChangeFilters'
          description: Engine, prompt and topic filters of the observation.
        key:
          anyOf:
            - type: string
            - type: 'null'
          title: Key
        pane:
          anyOf:
            - type: string
            - type: 'null'
          title: Pane
        route:
          title: Route
          type: string
      required:
        - route
        - pane
        - key
        - filters
      title: V1ChangeTarget
      type: object
    SurfaceAsOf:
      properties:
        at:
          description: When the displayed result was measured.
          format: date-time
          title: At
          type: string
        scan_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: The result's scan, null for a timestamp-only result.
          title: Scan Id
      required:
        - scan_id
        - at
      title: SurfaceAsOf
      type: object
    FirstCitation:
      properties:
        answer_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: Answer to open; null when no answer id can be recovered.
          title: Answer Id
        cited_at:
          description: When the citing answer was observed, after publication.
          format: date-time
          title: Cited At
          type: string
        display_name:
          description: Current engine name from the engine registry.
          title: Display Name
          type: string
        engine_id:
          description: Engine that cited the published page.
          title: Engine Id
          type: string
        mark_id:
          description: Engine id used to choose its visual mark.
          readOnly: true
          title: Mark Id
          type: string
        prompt:
          description: Prompt wording in the citing answer.
          title: Prompt
          type: string
        prompt_uid:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: Stable prompt id; null on older evidence without one.
          title: Prompt Uid
        scan_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: Read that observed this citation; null when not recorded.
          title: Scan Id
      required:
        - engine_id
        - display_name
        - prompt
        - prompt_uid
        - answer_id
        - cited_at
        - scan_id
        - mark_id
      title: FirstCitation
      type: object
    ChangeFilters:
      properties:
        engine:
          description: Engine whose answers changed.
          title: Engine
          type: string
        prompt:
          description: Prompt UUID when the change concerns one prompt.
          title: Prompt
          type: string
        topic:
          description: Topic under which the change was observed.
          title: Topic
          type: string
      required:
        - engine
        - prompt
        - topic
      title: ChangeFilters
      type: object
  securitySchemes:
    apiKey:
      description: 'An API key, sent as `Authorization: Bearer hrld_...`.'
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.