> ## Documentation Index > Fetch the complete documentation index at: https://docs.reputably.net/llms.txt > Use this file to discover all available pages before exploring further. # List reports > Reads reports in the selected workspace. Filter with `q`, a JSON object of field matches. Reads only: writes through this route are refused for every entity and every credential. ## OpenAPI ````yaml /openapi.json get /api/entities/Report openapi: 3.1.0 info: title: Reputably API version: 1.0.0 description: >- The HTTP surface an agent credential can reach. It is read plus safe writes: you can read your reputation data, generate drafts, queue reports and run first-time tracking setup. You cannot send anything to an external platform, trigger syncs, touch billing or manage credentials. The same endpoints back the MCP server, so anything documented here is reachable both ways. servers: - url: https://app.reputably.net description: Reputably - url: https://your-domain.example description: Your own verified white-label domain security: - agentKey: [] tags: - name: Businesses description: The locations you track, their plan usage and AI-generated insights. - name: Reviews description: Google and Facebook reviews, including which still need a reply. - name: Brand mentions description: Mentions across X, Reddit, YouTube, Facebook communities and the open web. - name: Brand tracking description: The trackers that find mentions, and competitor share of voice. - name: Leads description: Buying signals detected in mentions, with the public post to reply to. - name: AI Visibility description: >- Whether AI assistants recommend the business, what they cite, and how it moves. - name: AI Traffic description: Which AI crawlers read the website, and who arrives from an AI answer. - name: Posts description: Google Business Profile posts and drafts. - name: Reports description: Queued report renders and their CSV output. - name: Setup description: First-time tracking configuration. - name: Account description: Workspaces, notifications, sync status and prospect audits. paths: /api/entities/Report: get: tags: - Reports summary: List reports description: >- Reads reports in the selected workspace. Filter with `q`, a JSON object of field matches. Reads only: writes through this route are refused for every entity and every credential. operationId: listReport parameters: - name: q in: query required: false schema: type: string description: JSON filter object, for example {"needs_response":true}. - name: sort_by in: query required: false schema: type: string description: Field to sort on. - name: limit in: query required: false schema: type: integer description: Maximum rows to return. - name: skip in: query required: false schema: type: integer description: Rows to skip, for paging. - name: X-Workspace-Id in: header required: false schema: type: string description: >- Which workspace to read. Omit it and you get the account’s home workspace, which on an agency account is often not where the live businesses are. A workspace this credential cannot read is refused with 403 rather than quietly answered from the default. responses: '200': description: Matching reports. content: application/json: schema: type: array items: $ref: '#/components/schemas/Report' '401': description: Missing or invalid credential. '403': description: Not readable by this credential, or not in this workspace. components: schemas: Report: type: object title: Report properties: id: type: string description: Unique id. workspace_id: type: string template: type: string description: >- Which template to render. PR-9 ships only 'monthly_reputation_report'; PR-13 adds 'competitor_comparison'. Stored as a string (not enum) so adding new templates doesn't require a migration. period_start: type: string period_end: type: string status: type: string description: queued | rendering | completed | failed pdf_url: type: string description: >- Relative path under /uploads/reports//.pdf. Public — filename includes a UUID so URLs are unguessable. error_message: type: string description: >- Truncated render-failure reason. Surfaced to the user inline on the failed row. started_at: type: string completed_at: type: string render_token: type: string description: >- Short-lived JWT (~5min) the worker mints for the requested_by user so Puppeteer can authenticate against the SPA preview route. Cleared on completion. report_data: type: object description: >- Aggregated data the report renders from. Populated by the worker (server/lib/reportData.js) BEFORE Puppeteer launches, then never touched again — reports are immutable historical artifacts. Top-level keys are namespaced so future PRs extend cleanly: report_data.workspace, .agency, .period, .previousPeriod, .reputationScore, .reviews, .mentions, .responses are PR-10. PR-11 adds .business_location and .insights ({ topThemes, notableReviews, notableMentions, recommendations } — any of which may be null when its LLM call failed). PR-13's competitor template will add .competitors. Treat unknown keys as forward-compat; never assume the full shape. business_location_id: type: string description: >- BusinessLocation this report scopes its Reviews data to. PR-11+ requires this for new reports (enforced at the route, not the schema, so existing PR-10 rows with null values stay valid). Reports without it are labelled 'Workspace Rollup (Historical)' in the UI and cannot be shared. source: type: string scheduled_report_id: type: string description: >- When source='scheduled', points at the ScheduledReport that triggered this run. Lets the UI link back to the schedule's settings + retry buttons. period_label: type: string description: >- PR-14: human-readable period label, computed once at create time via server/lib/periodLabel.js. 'April 2026' for full calendar months, 'Q1 2026' for full calendar quarters, 'Mar 15 – Apr 28, 2026' otherwise. Stored on the row so the Reports list can render without recomputing per row. Older rows (pre-PR-14) have null and the UI falls back to computing from period_start/end on read. public_share_id: type: string description: >- Unguessable URL-safe token (12 chars, ~10²¹ search space). Generated when the agency owner enables sharing; cleared on disable; regenerated on re-enable so old URLs stay 404. Null when not currently shared. is_public: type: boolean description: >- Per-report public-share toggle. Independent of public_share_id presence — a report can have an old share_id with is_public=false (revoked); the public route requires both. share_view_count: type: integer description: >- Incremented on each public-page render. Async write — never blocks the response. No IP tracking in PR-11. share_created_at: type: string securitySchemes: agentKey: type: http scheme: bearer description: >- An agent key (`rpk_...`) created in Settings → API & MCP, sent as `Authorization: Bearer rpk_...`. Bearer only: a cookie session can never drive this API. An OAuth 2.1 access token obtained from the same host works identically and lands on the same ceiling. ````