> ## Documentation Index > Fetch the complete documentation index at: https://docs.tryprofound.com/llms.txt > Use this file to discover all available pages before exploring further. # Query Citations > Get citations for a given category. The ``mentioned`` filter supports ``is true`` and ``is false``. It uses the latest page analysis available at or before ``end_date``; pages without an analysis by then are excluded from both values. ``citation_share`` keeps all otherwise eligible citations in its denominator when this filter is used. ## OpenAPI ````yaml https://registry.scalar.com/@profound/apis/external-api/latest/openapi.json?variant=processed post /v1/reports/citations openapi: 3.1.0 info: title: External API version: 0.60.2 x-scalar-sdk-installation: - lang: Python description: |- ```sh pip install profound ``` - lang: TypeScript description: |- ```sh npm install @profoundai/client ``` - lang: Rust description: |- ```sh cargo add profound ``` servers: - url: https://api.tryprofound.com description: Production Server security: - APIKeyHeader: - X-API-Key - BearerAuth: [] paths: /v1/reports/citations: post: tags: - Reports - Reports summary: Query Citations description: >- Get citations for a given category. The ``mentioned`` filter supports ``is true`` and ``is false``. It uses the latest page analysis available at or before ``end_date``; pages without an analysis by then are excluded from both values. ``citation_share`` keeps all otherwise eligible citations in its denominator when this filter is used. operationId: query_citations_v1_reports_citations_post requestBody: content: application/json: schema: $ref: '#/components/schemas/CitationsQuery' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/CitationsResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] - BearerAuth: [] x-codeSamples: - label: Python lang: Python source: |- import os from profound import Profound client = Profound( api_key=os.environ.get("PROFOUND_API_KEY"), ) report = client.reports.citations( date_interval="day", dimensions=[], metrics=["count"], order_by={}, category_id="7c9e6679-7425-40de-944b-e07fc1f90ae7", start_date="2024-01-01T00:00:00.000Z", end_date="2024-01-01T00:00:00.000Z", ) print(report) - label: TypeScript lang: TypeScript source: |- import Profound from '@profoundai/client'; const client = new Profound({ apiKey: process.env['PROFOUND_API_KEY'], // defaults to the PROFOUND_API_KEY env var environment: 'production', }); const report = await client.reports.citations({ date_interval: 'day', dimensions: [], metrics: ['count'], order_by: {}, category_id: '7c9e6679-7425-40de-944b-e07fc1f90ae7', start_date: '2024-01-01T00:00:00.000Z', end_date: '2024-01-01T00:00:00.000Z', }); console.log(report); - label: rust lang: rust source: |- use profound::*; #[tokio::main] async fn main() -> Result<(), Box> { let client = ProfoundClient::builder() .api_key(std::env::var("PROFOUND_API_KEY")?) .build()?; let response = client .reports() .citations(CitationsQuery { date_interval: None, dimensions: None, metrics: vec![CitationsQueryMetric::Count], order_by: None, pagination: None, category_id: "7c9e6679-7425-40de-944b-e07fc1f90ae7".to_string(), start_date: chrono::Utc::now().fixed_offset(), end_date: chrono::Utc::now().fixed_offset(), filters: None, }) .send() .await?; println!("{:?}", response); Ok(()) } components: schemas: CitationsQuery: properties: date_interval: type: string enum: - hour - day - week - month - quarter - year - relative_week title: Date Interval description: Date interval for the report. (only used with date dimension) default: day dimensions: items: type: string enum: - hostname - path - date - region - topic - topic_id - model - tag - prompt - prompt_id - url - root_domain - persona - citation_category type: array title: Dimensions description: Dimensions to group the report by. default: [] metrics: items: type: string enum: - count - citation_share - share_of_voice - first_cited_at type: array title: Metrics description: >- Metrics to include. `share_of_voice` is deprecated, use `citation_share` instead. deprecated_values: share_of_voice: Use citation_share instead order_by: additionalProperties: type: string enum: - asc - desc type: object title: Order By description: |2- Custom ordering of the report results. The order is a record of key-value pairs where: - `key` is the field to order by, which can be a metric or dimension - `value` is the direction of the order, either `asc` for ascending or `desc` for descending. When not specified, the default order is the first metric in the query descending. default: {} examples: - date: asc - count: desc date: asc pagination: $ref: '#/components/schemas/Pagination' description: Pagination settings for the report results. category_id: type: string format: uuid title: Category Id start_date: type: string format: date-time title: Start Date description: >- Start date for the report. Accepts formats: YYYY-MM-DD, YYYY-MM-DD HH:MM, or full ISO timestamp. end_date: type: string format: date-time title: End Date description: >- End date for the report. Accepts formats: YYYY-MM-DD, YYYY-MM-DD HH:MM, or full ISO timestamp. filters: items: oneOf: - $ref: '#/components/schemas/HostnameFilter' - $ref: '#/components/schemas/PathFilter' - $ref: '#/components/schemas/RegionIdFilter' - $ref: '#/components/schemas/RegionNameFilter' - $ref: '#/components/schemas/TopicIdFilter' - $ref: '#/components/schemas/TopicNameFilter' - $ref: '#/components/schemas/ModelIdFilter' - $ref: '#/components/schemas/TagIdFilter' - $ref: '#/components/schemas/TagNameFilter' - $ref: '#/components/schemas/UrlFilter' - $ref: '#/components/schemas/RootDomainFilter' - $ref: '#/components/schemas/AnalysisTypeFilter' - $ref: '#/components/schemas/PromptTypeFilter' - $ref: '#/components/schemas/PersonaIdFilter' - $ref: '#/components/schemas/CitationCategoryFilter' - $ref: '#/components/schemas/PromptFilter' - $ref: '#/components/schemas/PromptIdFilter' - $ref: '#/components/schemas/MentionedFilter' discriminator: propertyName: field mapping: analysis_type: '#/components/schemas/AnalysisTypeFilter' citation_category: '#/components/schemas/CitationCategoryFilter' hostname: '#/components/schemas/HostnameFilter' mentioned: '#/components/schemas/MentionedFilter' model: '#/components/schemas/ModelIdFilter' model_id: '#/components/schemas/ModelIdFilter' path: '#/components/schemas/PathFilter' persona_id: '#/components/schemas/PersonaIdFilter' prompt: '#/components/schemas/PromptFilter' prompt_id: '#/components/schemas/PromptIdFilter' prompt_type: '#/components/schemas/PromptTypeFilter' region: '#/components/schemas/RegionIdFilter' region_id: '#/components/schemas/RegionIdFilter' region_name: '#/components/schemas/RegionNameFilter' root_domain: '#/components/schemas/RootDomainFilter' tag: '#/components/schemas/TagIdFilter' tag_id: '#/components/schemas/TagIdFilter' tag_name: '#/components/schemas/TagNameFilter' topic: '#/components/schemas/TopicIdFilter' topic_id: '#/components/schemas/TopicIdFilter' topic_name: '#/components/schemas/TopicNameFilter' url: '#/components/schemas/UrlFilter' type: array title: Filters description: List of filters to apply to the citations report. type: object required: - metrics - category_id - start_date - end_date title: CitationsQuery CitationsResponse: properties: info: $ref: '#/components/schemas/Info' data: items: $ref: '#/components/schemas/CitationsResult' type: array title: Data type: object required: - info - data title: CitationsResponse examples: - data: - dimensions: - example.com - /some/path - '2023-10-01' metrics: - 10 - 0.05 info: query: date_interval: day dimensions: - hostname - path - date filters: - field: hostname operator: is value: example.com metrics: - count - citation_share total_rows: 200 HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError Pagination: properties: limit: type: integer maximum: 50000 exclusiveMinimum: 0 title: Limit description: >- Maximum number of results to return. Default is 10,000, maximum is 50,000. default: 10000 offset: type: integer minimum: 0 title: Offset description: Offset for the results. Used for pagination. default: 0 type: object title: Pagination description: Offset-based pagination parameters. HostnameFilter: properties: field: type: string const: hostname title: Field operator: type: string enum: - is - not_is - in - not_in - contains - not_contains - matches - contains_case_insensitive - not_contains_case_insensitive title: Operator value: anyOf: - type: string - items: type: string type: array title: Value type: object required: - field - operator - value title: HostnameFilter description: Filter by hostname PathFilter: properties: field: type: string const: path title: Field operator: type: string enum: - is - not_is - in - not_in - contains - not_contains - matches - contains_case_insensitive - not_contains_case_insensitive title: Operator value: anyOf: - type: string - items: type: string type: array title: Value type: object required: - field - operator - value title: PathFilter description: Filter by request path RegionIdFilter: properties: field: anyOf: - type: string const: region_id - type: string const: region deprecated: true title: Field operator: type: string enum: - is - not_is - in - not_in title: Operator value: anyOf: - type: string format: uuid - items: type: string format: uuid type: array title: Value type: object required: - field - operator - value title: RegionIdFilter description: Filter by region UUID. RegionNameFilter: properties: field: type: string const: region_name title: Field operator: type: string enum: - is - not_is - in - not_in - contains - not_contains - matches - contains_case_insensitive - not_contains_case_insensitive title: Operator value: anyOf: - type: string - items: type: string type: array title: Value type: object required: - field - operator - value title: RegionNameFilter description: Filter by region name. TopicIdFilter: properties: field: anyOf: - type: string const: topic_id - type: string const: topic deprecated: true title: Field operator: type: string enum: - is - not_is - in - not_in title: Operator value: anyOf: - type: string format: uuid - items: type: string format: uuid type: array title: Value type: object required: - field - operator - value title: TopicIdFilter description: Filter by topic UUID. TopicNameFilter: properties: field: type: string const: topic_name title: Field operator: type: string enum: - is - not_is - in - not_in - contains - not_contains - matches - contains_case_insensitive - not_contains_case_insensitive title: Operator value: anyOf: - type: string - items: type: string type: array title: Value type: object required: - field - operator - value title: TopicNameFilter description: Filter by topic name ModelIdFilter: properties: field: anyOf: - type: string const: model_id - type: string const: model deprecated: true title: Field operator: type: string enum: - is - not_is - in - not_in title: Operator value: anyOf: - type: string format: uuid - items: type: string format: uuid type: array title: Value type: object required: - field - operator - value title: ModelIdFilter description: Filter by AI model/platform UUID. TagIdFilter: properties: field: anyOf: - type: string const: tag_id - type: string const: tag deprecated: true title: Field operator: type: string enum: - is - not_is - in - not_in title: Operator value: anyOf: - type: string format: uuid - items: type: string format: uuid type: array title: Value type: object required: - field - operator - value title: TagIdFilter description: Filter by tag (prompt group) UUID. TagNameFilter: properties: field: type: string const: tag_name title: Field operator: type: string enum: - is - not_is - in - not_in - contains - not_contains - matches - contains_case_insensitive - not_contains_case_insensitive title: Operator value: anyOf: - type: string - items: type: string type: array title: Value type: object required: - field - operator - value title: TagNameFilter description: Filter by tag name. UrlFilter: properties: field: type: string const: url title: Field operator: type: string enum: - is - not_is - in - not_in - contains - not_contains - matches - contains_case_insensitive - not_contains_case_insensitive title: Operator value: anyOf: - type: string - items: type: string type: array title: Value type: object required: - field - operator - value title: UrlFilter description: Filter by URL RootDomainFilter: properties: field: type: string const: root_domain title: Field operator: type: string enum: - is - not_is - in - not_in - contains - not_contains - matches - contains_case_insensitive - not_contains_case_insensitive title: Operator value: anyOf: - type: string - items: type: string type: array title: Value type: object required: - field - operator - value title: RootDomainFilter description: Filter by root domain AnalysisTypeFilter: properties: field: type: string const: analysis_type title: Field operator: type: string enum: - is - not_is - in - not_in - contains - not_contains - matches - contains_case_insensitive - not_contains_case_insensitive title: Operator value: anyOf: - type: string enum: - visibility - sentiment - sentiment_v2 - accuracy - items: type: string enum: - visibility - sentiment - sentiment_v2 - accuracy type: array title: Value type: object required: - field - operator - value title: AnalysisTypeFilter description: Filter by analysis type (visibility, sentiment, or accuracy). PromptTypeFilter: properties: field: type: string const: prompt_type title: Field operator: type: string enum: - is - not_is - in - not_in - contains - not_contains - matches - contains_case_insensitive - not_contains_case_insensitive title: Operator value: anyOf: - type: string enum: - visibility - sentiment - items: type: string enum: - visibility - sentiment type: array title: Value type: object required: - field - operator - value title: PromptTypeFilter description: |- Filter by prompt type (visibility or sentiment). .. deprecated:: Use :class:`AnalysisTypeFilter` instead. ``prompt_type`` is normalised to ``analysis_type`` at parse time. PersonaIdFilter: properties: field: type: string const: persona_id title: Field operator: type: string enum: - is - not_is - in - not_in title: Operator value: anyOf: - type: string format: uuid - items: type: string format: uuid type: array title: Value type: object required: - field - operator - value title: PersonaIdFilter description: Filter by persona UUID. CitationCategoryFilter: properties: field: type: string const: citation_category title: Field operator: type: string enum: - is - not_is - in - not_in - contains - not_contains - matches - contains_case_insensitive - not_contains_case_insensitive title: Operator value: anyOf: - type: string - items: type: string type: array title: Value type: object required: - field - operator - value title: CitationCategoryFilter description: Filter by citation category PromptFilter: properties: field: type: string const: prompt title: Field operator: type: string enum: - is - not_is - in - not_in - contains - not_contains - matches - contains_case_insensitive - not_contains_case_insensitive title: Operator value: anyOf: - type: string - items: type: string type: array title: Value type: object required: - field - operator - value title: PromptFilter description: Filter by prompt text PromptIdFilter: properties: field: type: string const: prompt_id title: Field operator: type: string enum: - is - not_is - in - not_in title: Operator value: anyOf: - type: string format: uuid - items: type: string format: uuid type: array title: Value type: object required: - field - operator - value title: PromptIdFilter description: Filter by prompt UUID. MentionedFilter: properties: field: type: string const: mentioned title: Field operator: type: string const: is title: Operator value: anyOf: - type: boolean - items: type: boolean type: array title: Value type: object required: - field - operator - value title: MentionedFilter description: Filter citation pages by whether they mention an owned category asset. Info: properties: total_rows: type: integer title: Total Rows query: anyOf: - additionalProperties: true type: object - type: 'null' title: Query type: object required: - total_rows title: Info description: Base model for report information. CitationsResult: properties: metrics: items: anyOf: - type: integer - type: number - type: string - type: 'null' type: array title: Metrics dimensions: items: anyOf: - type: string - type: string format: uuid type: array title: Dimensions type: object required: - metrics - dimensions title: CitationsResult ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError securitySchemes: APIKeyHeader: type: apiKey in: header name: X-API-Key BearerAuth: type: http scheme: bearer bearerFormat: JWT ````