> ## Documentation Index > Fetch the complete documentation index at: https://docs.spreadjam.com/llms.txt > Use this file to discover all available pages before exploring further. # Read the research state > The active project's research: whether it is running, when the latest run started and finished and how it ended, the request in flight, whether Research again would be accepted and what it holds (500 credits once the project has a successful run; the first run is free), and whether Jam's free automatic top-up could run. ## OpenAPI ````yaml https://api.spreadjam.com/openapi.json get /v1/research openapi: 3.0.0 info: title: SpreadJam API version: 1.0.0 servers: - url: https://api.spreadjam.com security: [] tags: - name: Meta description: Identity and metadata about the authenticated key. - name: Keywords description: Keyword and topic visibility rankings. - name: API keys description: Manage the workspace's API keys. - name: Analytics description: AI-visibility analytics for the workspace. - name: Brand description: The workspace's brand profile and competitors. - name: Prompts description: Tracked GEO prompts and their cap state. - name: Visibility runs description: Run the AI-visibility scan now. - name: Credits description: The workspace's credit balance and recent charges. - name: Actions description: Recommended visibility actions and reporting them done. - name: Agent connect description: >- Sign a human up from an agent with one link, then receive an API key once they approve. No API key needed. - name: Pricing description: >- The plans an agent can choose for a human and their monthly prices. No API key needed. - name: Site changes description: >- Code changes Jam prepares for page edits and technical fixes: preview, open the pull request, discard. - name: Research description: >- The research that writes the Plan: its state, its latest report, and running it again. - name: Answers description: >- What each AI platform answered to the tracked prompts, with the sources it cited. - name: Projects description: The workspace's projects and the status of each one. - name: Billing description: The workspace's plan and the links where a person manages billing. - name: Webhooks description: >- HTTP destinations the workspace notifications are POSTed to, signed with a per-webhook secret. - name: Notifications description: >- Which notifications reach which channels (including webhooks), per event category. - name: Opportunities description: >- Article opportunities: the article pipeline behind the Plan's `new_page` actions, and requests to create content from them. - name: Planning description: Run automatic content planning now. - name: Content description: Content items, their drafts, and requests to rewrite them. - name: Revisions description: A content item's revisions. - name: Publishing description: Publishing content to destinations, now or on a schedule. - name: Deliveries description: A content item's delivery history. - name: Publications description: Where a content item is live. - name: Destinations description: Where content is published, its publishing policy, and its connection. paths: /v1/research: get: tags: - Research summary: Read the research state description: >- The active project's research: whether it is running, when the latest run started and finished and how it ended, the request in flight, whether Research again would be accepted and what it holds (500 credits once the project has a successful run; the first run is free), and whether Jam's free automatic top-up could run. operationId: get_research responses: '200': description: The research state. content: application/json: schema: $ref: '#/components/schemas/ResearchState' '400': description: >- Invalid request: a parameter or body field is wrong. `details` lists each problem with what is allowed. content: application/json: schema: $ref: '#/components/schemas/ApiError' '401': description: >- Missing, malformed or revoked API key (`Authorization: Bearer sk_…`). content: application/json: schema: $ref: '#/components/schemas/ApiError' '404': description: The workspace has no GEO project. content: application/json: schema: $ref: '#/components/schemas/ApiError' '429': description: >- `rate_limited` (per-key rate) or `too_many_concurrent` (expensive reads in flight); retry after `Retry-After` seconds. content: application/json: schema: $ref: '#/components/schemas/ApiError' security: - bearerAuth: [] components: schemas: ResearchState: type: object properties: state: type: string enum: - never - running - done - failed startedAt: type: string nullable: true format: date-time finishedAt: type: string nullable: true format: date-time latest: type: object nullable: true properties: requestId: type: string format: uuid kind: type: string enum: - first_scan - backfill - manual - top_up description: >- `first_scan`: the free run after the first scan. `backfill`: a free run for a project that had none. `manual`: Research again (charged after the first success). `top_up`: Jam's free weekly re-run when the Plan runs low; it only adds rows. requestedAt: type: string format: date-time startedAt: type: string nullable: true format: date-time finishedAt: type: string nullable: true format: date-time outcome: type: string nullable: true enum: - success - failed - abandoned - null failureMessage: type: string nullable: true required: - requestId - kind - requestedAt - startedAt - finishedAt - outcome - failureMessage inFlight: type: object nullable: true properties: requestId: type: string format: uuid kind: type: string enum: - first_scan - backfill - manual - top_up description: >- `first_scan`: the free run after the first scan. `backfill`: a free run for a project that had none. `manual`: Research again (charged after the first success). `top_up`: Jam's free weekly re-run when the Plan runs low; it only adds rows. requestedAt: type: string format: date-time required: - requestId - kind - requestedAt description: The run in flight, if any. Runs take about ten minutes. manual: type: object properties: eligible: type: boolean description: The workspace's plan includes research. free: type: boolean description: >- The next run is free: the project has never had a successful run. credits: type: integer description: >- Credits `POST /v1/research-requests` holds now (kept only if the run succeeds); 0 when free. blockedBy: type: string nullable: true enum: - plan_required - in_progress - first_scan_running - null description: >- Why a request would be refused now; null when it would be accepted (credits permitting). required: - eligible - free - credits - blockedBy description: Research again, by hand. automaticTopUp: type: object properties: eligibleNow: type: boolean notBefore: type: string nullable: true format: date-time required: - eligibleNow - notBefore description: >- Jam's free automatic re-run: at most once a week, after a successful run, once a scan has new answers, and only while the Plan has fewer than 5 untouched article rows. `notBefore` is when the weekly limit next allows one. required: - state - startedAt - finishedAt - latest - inFlight - manual - automaticTopUp ApiError: type: object required: - error - code properties: error: type: string description: What went wrong and how to fix the request. code: type: string description: >- Stable machine-readable code, e.g. invalid_request, unauthorized, rate_limited. requestId: type: string description: Echoes the X-Request-Id header; quote it to support. docs: type: string description: Where the error is explained. resolveUrl: type: string description: '402/403 plan errors: the dashboard page that resolves it.' details: type: array description: >- One entry per problem: path, message, and when known allowed, minimum, maximum, expected, received. items: type: object additionalProperties: true securitySchemes: bearerAuth: type: http scheme: bearer description: >- A workspace API key issued in Settings → Developer, sent as `Bearer sk_…`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.