Question GET list

GET /questions

Returns a list of published questions. By default, all published questions are returned, ordered by their last activity (descending). A combination of filters, search queries and ordering criteria can be applied to the list, as documented below.

When a query parameter is provided, only questions that match the given query are returned. If no sort parameter is specified, then the questions that are most relevant for the given query are returned first. If sort is specified, then the output will be sorted according to the specified sort criteria (which might deliver less meaningful results first). Consult the Concepts section for more technical details about search.

Parameter Type Default Required Description
limit int 10 Limits the number of returned question
offset int 0 Offset for pagination.
user_id int Show only questions posed by this user.
Notice For a normal user this may only be his own ID. For admin users there is a special permission required to retrieve the questions for a given user id.
filter string Filter the list of questions using a predefined filter. Allowed filters are:
  • solved Show solved questions
  • unsolved Show unsolved questions
  • my-questions Show questions you have posed
  • my-solutions Show question you have contributed a solution to
  • following Show question you are currently following
  • flagged Show questions that have been flagged
  • trending Show questions that are trending in the network
Combining multiple filters is possible by specifying a comma-separated list (my-questions,unsolved). They are combined using a logical AND condition. Joining incompatible filters may lead to an empty result.

If the parameter user_id is specified, then the filters are ignored.

Using the trending filter automatically sorts the questions by how trending they are, overriding the sort parameter.
tags string - Specify a comma separated list of tag labels by which the questions are filtered. The tags are checked using a logical AND condition - that means only questions with all the specified tags will be returned.
sort string last_activity.desc Specify the criteria the result is sorted by. The allowed sort criteria are last_activity, solution_count, date_published, view_count, id.
The format is CRITERION.DIRECTION,CRITERION.DIRECTION.

The criterion views is deprecated in favour of view_count to reflect naming of response parameter.

This parameter overrules the result ordering of the query parameter.
query string - Query to search by. The resulting questions are sorted by relevance for the given search query (unless a sort parameter overrides this behaviour).
query_default_operator string OR When the query parameter consist of several words, this pamater defines how these words are combined during the search:
  • AND only returns questions where all words in the query are matched. Moreover, they must all be matched within the same field: e.g. a question where one word is only found in the title and another word is only found in a solution, will not be returned. Similar questions (more info) will not be considered when using the AND operator.
  • OR also returns questions where only some of the words in the search query are matched. Also with this option, in the list of search results, questions where all words in the query are matched will generally appear above questions where only some words are matched.
If the parameter is missing or if an invalid value is specified, the OR operator will be used.

Warning: in the future, additional functionality will be added to give further control over which words in a search query must be matched and which words are optional. Afterwards, this parameter may be removed again from the API at relatively short notice.
query_fields string - (all fields) A comma-separated list of fields names, where each field name is one of the following:
  • title
  • description
  • tags
  • solutions
  • comments
  • attachments
If a list of field names is specified, then the question search will only match the provided query in those parts of each question. Invalid field names are ignored. If no query_fields parameter is specified, then all fields will be included.

Similar questions (more info) will only be considered if the fields title, description, tags and solutions are all included, since the similarity algorithm depends on all of these fields.
include_deleted boolean false If set to true and the user has the required permission, the response will include deleted questions.
category string all Filter the list of questions by a specific category. Possible values are:
  • uncategorised only returns questions which have no category assigned to them.
  • all returns all questions, no matter what category they belong to.
  • `category-id` only returns questions which are assigned to that specific category.(more info)
log_query boolean false If set to true and if offset == 0 and query is defined, the query will be logged and a search_query_id will be added to the response.

Response

If a query is specified in the request, then every item in the response will have an additional field search_metadata. The search_metadata object contains:

  • score
  • is_relevant if the item is determined to be significantly relevant to the user query
  • highlighting object if highlighting can be applied

Score

The score of a question is a positive floating-point value that expresses how well the question fits the given search query, with better matches having a higher score. If no other sort parameter is specified in the request, then the results will be sorted by this score in descending order.

The scores of the results of any query are always roughly centred around 1.0. Questions that contain the search query in their title will generally score clearly higher than 1.0. Question where the search query is only found in some comment or attachment will generally score clearly lower than 1.0. As such, a value around 1.0 could be useful as a threshold to keep only highly relevant search results.

Highlighting

The highlighting object of a question is defined by the properties query_field, id, fragment, start, and end, which correspond to the element of the question that best matches the provided search query. If no highlighting can be applied to a question, then the question will not have a highlighting object. The query_field is the field name of the highlighted element, which is one of those included in the query_fields parameter or any of them if the parameter is not specified in the query. The relation between query_field and id is defined as follows:

query_field id
title The id of the question
description The id of the question
tags The id of the question
solutions The id of the best matching solution
comments The id of the best matching comment
attachments The id of the best matching attachment

The property fragment contains a fragment of the text, in which the matched words from the search query are surrounded by <em> tags. Apart from the <em> tags, the highlighted fragment is HTML encoded, so this string can be used without risk of HTML injections. If the best matching query_field is the title, then the fragment always contains the entire title.

The properties start and end are boolean values that define the position of the fragment in the full text. start is true for those fragments that start at the beginning of the text, and end is true for those that end at the end of the text. Additionally, this means that if start and end are both true, then the whole fragment covers the full text, and if startand end are both false, then the fragment is in the middle. These values may be used to decide whether to add an ellipsis (...) in front of and/or after the fragment when displaying the fragment to the user.

Logging

If the parameter log_query is set to false, the response will not contain search_query_id.

If the parameter log_query is set to true and offset == 0 and query is defined:

  • The query will be logged.
  • The response will include a non-null integer search_query_id.

Warning: Logging should only be enabled when the query and the ensuing clicks may be used for learning about the user's interest and for optimising the ranking of results on future search queries.

{
    "search_query_id": 123,
    "total": 1,
    "_links": {
        "self": {
            "href": "/api/v1/questions?tags=sherlock&query=holmes&offset=0&limit=10&log_query=true"
        }
    },
    "items": [
        {
            "description": null,
            "solution_count": 1,
            "slug": "is-there-a-study-in-scarlet",
            "id": 21,
            "updated": "2015-02-02T11:36:05.000Z",
            "content_updated": "2015-02-02T11:36:05.000Z",
            "last_activity": "2015-02-02T11:41:08.000Z",
            "image": "https://cdn.example.com/avatar/default/2d/1b84215e2f035a22f6fec213d3b1d9.jpg",
            "language": "en",
            "tag_relations": [
                {
                    "tag": "Study",
                    "is_auto": true
                }
            ],
            "title": "Is there a Study in Scarlet?",
            "attachments": "/questions/21/attachments",
            "is_published": true,
            "published": "2015-02-02T11:36:05.000Z",
            "created": "2015-02-02T11:31:05.000Z",
            "is_deleted": false,
            "view_count": 28,
            "search_metadata": {
              "highlighting": {
                "query_field": "solutions",
                "fragment": "Dr Watson, Sherlock <em>Holmes</em> partner Astrid Farnsworth",
                "id": 1092,
                "start": true,
                "end": false
              },
              "score": 5.8311359538639,
              "is_relevant": true
            },
            "upvote_count": 23
        }
    ]
}